MCP Tools Explained: Schemas, Annotations and Write Tiers

In the Model Context Protocol, a tool is a function that a server exposes for an AI model to call. MCP servers can offer three kinds of feature: resources, which are context and data; prompts, which are templated messages and workflows; and tools, which the specification describes as functions for the model to execute. Tools are the part that does things, which is why most security questions about MCP are really questions about tools.

Anatomy of a tool

The MCP specification defines a tool with a small set of fields:

• name: a unique identifier.
• title: an optional human-readable name for display.
• description: what the tool does, written for the model as much as for people.
• inputSchema: a JSON Schema for the parameters.
• outputSchema: an optional JSON Schema for structured output.
• annotations: optional hints about behaviour.

A client finds tools by sending tools/list, which supports pagination, and runs one with tools/call, passing the tool name and arguments. A server that adds or removes tools can tell the client with a notifications/tools/list_changed message.

Annotations are hints, not guarantees

The specification’s annotation vocabulary includes hints such as readOnlyHint and destructiveHint, and it is explicit that clients must treat tool annotations as untrusted unless they come from trusted servers. A tool marked read-only by its author is only as trustworthy as that author. It also says that, for trust and safety, there should always be a human in the loop able to deny tool invocations, and that applications should show which tools are exposed, indicate when a tool is invoked, and prompt for confirmation.

The practical conclusion: do not rely on the client or the model to enforce what a tool may do. Enforce it on the server side, where the caller’s identity and permissions are known.

How ZopNight groups its tools

ZopNight’s MCP server exposes read tools and mutating tools across its product areas:

• Read tools cover resources, schedules, costs, recommendations, teams, budgets, audit logs, billing sync, dashboards, the autoscaler, event readiness, governance and policy, and the ZopDay delivery surface: deploys, infrastructure, migrations, and components.
• Mutating tools cover budgets, schedules, overrides, deploys, start and stop, provisioning, deletes, teams, roles and members, notifications, integrations, the autoscaler, event readiness, policies, and infrastructure lifecycle.

The exact counts change with each release and are kept in the MCP server’s own documentation, so they are not repeated here.

How ZopNight gates them

ZopNight does not trust annotations to decide what runs. Every call is decided at the gateway:

• The organization must have MCP enabled, and the caller must authenticate with a personal access token.
• Read tools are checked against the caller’s live role.
• Mutating tools also need the organization’s write tier to admit them. Tiers run from none, the default, through metadata-only and reversible to irreversible, and the irreversible tier also needs an organization-bound token. The token’s own scope must allow the tool too.
• The whole write surface sits behind a kill switch that is off by default.
• tools/list is filtered to exactly what the caller may call, so a tool that would be refused is not advertised.

Role and member management sit at tier 1, and bulk start and stop at tier 3. A few areas have no tool at any tier: organization deletion, cloud-account deletion, credential reads, and org-level role assignment.

Designing questions for tools

Tools with filters work best when the question is specific. “Top idle compute in the production account by monthly cost” maps onto a filtered list call; “tell me about my cloud” makes the model page through everything. ZopNight’s list tools forward filters such as provider, status, region, search, and sort for this reason.

For connection, tiers, and audit, see the ZopNight MCP server; for the broader picture, see MCP and AI cloud management.