Get the plugin
WP MCP/Blog/Post

By · Published

MCP tools explained: schemas, calls and annotations

explainermcp

MCP tools explained: schemas, calls and annotations

MCP tools are the part of the protocol most people mean when they say an AI “can do things” on a system. A tool is a named action with a described input. The model reads the list, picks one, fills in the arguments and the client runs it on the server.

This article covers what a tool definition contains, how listing and calling work, how errors and annotations behave, and what it means when a server has hundreds of tools, as a WordPress site with WP MCP does. The wire details come from the official specification at modelcontextprotocol.io, checked on the 2025-11-25 and 2026-07-28 revisions. For the full message flow around tools, see MCP protocol explained.

What an MCP tool is

The specification describes tools as model-controlled: the language model can discover and invoke them from its understanding of the conversation. The protocol does not force a particular interface, but it says there should always be a human in the loop with the ability to deny a call, and that apps should make clear which tools are exposed and when one runs.

A server that has tools declares a tools capability, optionally with listChanged: true to say it will notify when the list changes.

Tools are one of three things a server can offer. Resources and prompts are covered in MCP resources and prompts. If you want the broader idea of a server first, read what an MCP server is, and for how a tool differs from a plain REST endpoint see MCP vs API.

Anatomy of a tool definition

A tool definition has these fields.

  • name: the unique identifier. The specification says names should be 1 to 128 characters, case-sensitive, and limited to letters, digits, underscore, hyphen and dot.
  • title: an optional human-readable name for display.
  • description: plain text that tells the model what the tool does. This is the text the model reads to decide.
  • inputSchema: a JSON Schema object for the arguments. It must be a valid object schema, never null. A tool with no parameters uses { "type": "object", "additionalProperties": false }.
  • outputSchema: an optional schema for structured results.
  • annotations: optional hints about behaviour.

Here is a WordPress example. This is an illustrative definition shaped like what WP MCP advertises for its post-reading tool.

{
  "name": "wpmcp-get-post",
  "description": "Read a post's full content, status, terms, meta, and featured image",
  "inputSchema": {
    "type": "object",
    "properties": {
      "post_id": { "type": "integer", "description": "The post ID" }
    },
    "required": ["post_id"]
  },
  "annotations": { "readOnlyHint": true }
}

WP MCP’s tools are registered as WordPress abilities named like wpmcp/get-post. The MCP layer turns the slash into a hyphen so the name fits the specification’s character rules, which is why a client sees wpmcp-get-post. The description and schema are the whole interface the model has, so a vague description or a loose schema produces wrong calls. That is true of any server, and it is a good place to look when an agent picks the wrong tool.

The MCP tools list: how a client discovers tools

A client lists tools with tools/list. The request supports pagination through a cursor, and a server returns a nextCursor when there is more.

{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }

The response carries a tools array of definitions like the one above. On the 2026-07-28 revision the result also carries cache fields, ttlMs and cacheScope, so a client can keep the list for a while instead of fetching it again.

Two points about the list on 2026-07-28 are worth knowing. A server should return tools in a deterministic order, which helps clients cache the list and helps model prompt caching. And the set may vary by the authorization on the request, for example by showing only the tools the caller’s scopes allow, but it must not vary by connection or as a side effect of other requests.

If the server’s list changes while the client is connected, it sends notifications/tools/list_changed and the client lists again. On 2026-07-28 that notification reaches a client that has opened a subscriptions/listen stream with toolsListChanged: true.

Getting a tools list without an AI app

You can read the list yourself in two ways:

  • Open the endpoint in MCP Inspector and look at the Tools tab. The MCP Inspector guide shows the steps for a WordPress site.
  • On a WP MCP site, call the catalog tool. list-tool-catalog returns every registered tool grouped by domain, with its tier (free or Pro), its operation, its capability and its read-only and destructive hints, plus a count per domain. A search term narrows it. Because it reports what is registered on that site, it is the honest answer to “which tools does my site have”, since tools for optional plugins such as ACF, SEO plugins and form plugins only register where that plugin is active.
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "wpmcp-list-tool-catalog",
    "arguments": { "search": "woocommerce" }
  }
}

Calling a tool

A client runs a tool with tools/call, passing the name and an arguments object that matches the schema.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "wpmcp-get-post",
    "arguments": { "post_id": 42 }
  }
}

The result holds a content array. Each item has a type: text, image, audio, a resource link or an embedded resource. A tool can also return structuredContent, a JSON value that follows its outputSchema. For compatibility the specification says a tool that returns structured content should also return the serialized JSON as a text block. On 2026-07-28 results carry a resultType field as well, with the value complete for a finished call.

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      { "type": "text", "text": "{\"post_id\":42,\"title\":\"Spring sale\",\"status\":\"draft\"}" }
    ],
    "isError": false
  }
}

The text above is an example of the shape. Real WP MCP responses carry more fields. A write tool returns an operation_id, which matters in the next section.

Two kinds of error

The specification separates failures into two layers, and the difference decides whether a model can recover.

Protocol errors are standard JSON-RPC errors. They cover an unknown tool, a request that does not match the call schema, and server faults. The specification notes that models are less likely to recover from these.

{ "jsonrpc": "2.0", "id": 3, "error": { "code": -32602, "message": "Unknown tool: invalid_tool_name" } }

Tool execution errors are returned inside a normal result with isError: true. They cover failed API calls, bad input values and business-rule failures. Clients should pass them to the model so it can correct itself and try again.

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{ "type": "text", "text": "Invalid status: use draft, pending, private or publish." }],
    "isError": true
  }
}

For tool authors the practical rule is to write error text a model can act on. “Invalid status, use one of these” fixes a call. “Error 500” does not.

Annotations: hints, not guarantees

The annotations object holds optional hints. The specification defines title, readOnlyHint, destructiveHint, idempotentHint and openWorldHint.

Annotation Meaning Default
readOnlyHint The tool does not modify its environment false
destructiveHint The tool may perform destructive updates, otherwise only additive ones. Meaningful only when not read-only true
idempotentHint Repeating the call with the same arguments has no additional effect. Meaningful only when not read-only false
openWorldHint The tool may interact with an open world of external entities, such as the web true

Clients use these to decide how much to ask a person. A read-only tool can often run without a prompt, and a destructive one gets a confirmation. The specification is explicit that clients must consider annotations untrusted unless they come from a trusted server, and should never base tool-use decisions on annotations from an untrusted one. So treat them as a convenience for approvals and not as a security control. The real control is what the server enforces when the call arrives.

WP MCP sets the read-only, destructive and idempotent hints on its tools, and list-tools with full: true and get-tool-schema both show them. Destructive tools also take a confirm: true argument, and on clients that support form elicitation the plugin asks the person instead of refusing.

Reads, writes and undo

The tool surface of a real site shows why the read and write split matters. In WP MCP:

  • Reads such as wpmcp-get-post, wpmcp-list-posts and wpmcp-search-content change nothing.
  • Writes such as wpmcp-update-post are wrapped by a safety engine. Before a supported write, the plugin stores a snapshot, then verifies the result and rolls back on its own if the check fails. The response includes an operation_id.
  • Undo is a tool too. wpmcp-rollback-operation takes that operation_id and restores the earlier state, and wpmcp-rollback-session unwinds everything an agent session did.
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "wpmcp-rollback-operation",
    "arguments": { "operation_id": "<the id returned by the write>" }
  }
}

Some changes cannot be snapshotted, such as package updates and raw database row writes. Those tools are off by default, ask for confirm: true, and say in their response that they cannot be undone. For example, update-plugin is disabled until the site opts in and is not rollback-able. The revisions and undo guide explains how the undo side works, and MCP security for WordPress covers how to limit what an agent can call.

Free and Pro tools use the same mechanics. WP MCP registers 407 tools in total, 274 free and 133 Pro. Pro tools such as wpmcp-get-elementor-data and wpmcp-add-container edit Elementor pages, and you can see which page builders and plugins are covered on the Elementor, WooCommerce and ACF integration pages.

When there are too many tools

Every tool in tools/list costs tokens, because the model receives each name, description and schema. Some clients also cap the number of tools they accept. A site with a few hundred tools therefore has a real design problem.

WP MCP’s answer is compact mode, which is off by default. It advertises five tools: list-tools, get-tool-schema, call-tool, get-connection-info and get-site-context. Every other tool stays reachable through call-tool. The flow looks like this:

  1. The agent calls wpmcp-list-tools with a search term to find candidates.
  2. It calls wpmcp-get-tool-schema for the one it wants, which returns the exact input schema and annotations.
  3. It calls wpmcp-call-tool with the tool name and an arguments object.
{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "wpmcp-call-tool",
    "arguments": {
      "name": "wpmcp/get-post",
      "arguments": { "post_id": 42 }
    }
  }
}

Compact mode only changes what is advertised. It is not a permission boundary: a dispatched call runs the target tool’s own capability check, rate limit, validation and snapshot behaviour as if it had been called directly. The README reports a measured tools/list payload for version 0.8.180 in a test environment of 135,075 bytes across 270 tools in full mode against 2,265 bytes across 5 tools in compact mode. That is one measurement on one setup, so treat it as a sense of scale. You can set the mode site-wide, per scoped identity, or in code with the wpmcp_tool_exposure_mode option or filter.

Writing good tools, if you build servers

If you build your own server, the same lessons apply at small scale. The guide to building an MCP server covers the mechanics, and these habits help:

  • Name tools by verb and object, and keep names within the allowed characters.
  • Write descriptions for the model, with what the tool does and when not to use it.
  • Keep schemas tight: required fields, enums for fixed choices, descriptions on every property.
  • Return errors a model can act on.
  • Mark read-only tools as read-only, and keep destructive actions behind an explicit confirmation.
  • Validate every input on the server, whatever the schema says.

For what WP MCP exposes on a real site, see the WordPress MCP server page. The MCP server examples show other servers’ tool sets, and the MCP tutorial walks through connecting and calling a first tool. Pro adds deep page builder editing and the agent memory tools, and its plans are on the pricing page.

Common questions

What are MCP tools?

MCP tools are actions a server offers to an AI model. Each tool has a name, a description and a JSON Schema for its inputs. The client lists them with tools/list and runs one with tools/call, and the model decides when to use which, usually with the user's approval for anything that changes data.

How do I get an MCP tools list?

Send a tools/list request to the server, or open the connection in MCP Inspector and read the Tools tab. On a WP MCP site you can also call list-tool-catalog, which groups every registered tool by domain with its free or Pro tier and its read-only and destructive hints.

What is the difference between a tool, a resource and a prompt?

A tool is something the model can call, and it may change things. A resource is data the app can read, such as a document. A prompt is a reusable template a person picks. Tools are model-controlled, while resources and prompts are usually chosen by the app or the user.

What do the readOnlyHint and destructiveHint annotations mean?

They are optional hints about behaviour. readOnlyHint says the tool does not modify its environment. destructiveHint says it may perform destructive updates, and it only matters when the tool is not read-only. The specification tells clients to treat annotations from untrusted servers as untrusted, so they are not a security boundary.

How many tools can an MCP server expose?

The protocol sets no limit, but clients and models do. Every tool in tools/list costs tokens, and some clients cap the count. WP MCP registers up to 407 tools and offers a compact mode that advertises five and reaches the rest through call-tool.

What happens when a tool call fails?

There are two kinds of failure. A protocol error, such as an unknown tool, is a JSON-RPC error. A failure inside the tool, such as invalid input, comes back as a normal result with isError set to true so the model can read the message and retry with better arguments.