Reading an MCP Tool Definition Before You Trust It

When an AI application connects to an MCP server, it asks for the list of tools the server offers with a tools/list request. Each entry tells the model what it may call and how. That list is the contract you are approving, so it is worth knowing what is in it. This guide summarises the Tools page of the MCP specification, revision 2026-07-28, as read on 29 October 2026. It describes what the specification says servers and clients should do, not what any given server actually does.

Tools are model-controlled

The specification says tools are designed to be model-controlled: the language model can discover and invoke them automatically based on context and the user's prompts. It adds that, for trust and safety, a person should always be able to veto a tool call. Applications should make clear which tools are exposed to the model, show visual indicators when tools are invoked, and present confirmation prompts. If the app you use does none of this, that is a gap in the app, not a feature of the protocol.

What a definition contains

• A name that identifies the tool, and an optional human-readable title.
• A description of what the tool does, written in words the model reads.
• An input schema in JSON Schema that defines the expected parameters.
• An optional output schema describing the structure of the result.
• Optional annotations describing the tool's behaviour.
• Optional icons for display.

Two points matter for trust. First, annotations count as untrusted unless the server itself is trusted, so a tool that labels itself harmless has not proved anything. Second, in our reading, a description is text supplied by the server that helps the model decide what to call, so it deserves the same scrutiny as any other text from an outside source.

Names, lists and changes

Tool names should run from 1 to 128 characters, be case-sensitive, and limited to letters, digits, underscores, hyphens and dots. They should be unique within one server. The specification notes that two servers may each expose a tool with the same name, and that clients combining several servers should disambiguate, for example by prefixing the server identifier. The list of tools can be empty and can change over time, but must not differ between connections or shift because of unrelated requests. It may differ with the authorization presented on a request, for example showing only the tools the caller's granted scopes allow. Servers should keep the order of tools stable.

Results and errors

A tool result can contain text, images, audio, links to resources and embedded resources. A result may also include structured content, and when a server publishes an output schema it must provide structured results that conform to it, while clients should validate them. Errors come in two kinds. Protocol errors, such as an unknown tool or a malformed request, are returned as standard JSON-RPC errors. Tool execution errors, such as API failures, input validation errors and business logic errors, are reported in the result with isError set to true. The specification says clients should pass execution errors to the model so it can correct itself, which is one reason a failing tool can burn many calls. See diagnosing tool call failures.

What the specification asks servers and clients to do

• Servers must validate all tool inputs, implement access controls, rate limit invocations and sanitize outputs.
• Clients should ask for confirmation on sensitive operations and show users the inputs before a call is sent, to head off accidental or malicious data leaks.
• Clients should validate tool results before passing them to the model, implement timeouts, and log tool usage for audit.
• Servers should not mark sensitive parameters such as passwords, API keys or tokens for mirroring into HTTP headers, because header values are visible to network intermediaries.

A review checklist (our suggestions)

• Read every tool name and description. Which tools can write, delete, send or spend? Those need a person approving each call; see agent tool permissions.
• Look at the input schema. A tool that accepts free text where a fixed choice would do gives the model more room to go wrong. Pair it with argument validation.
• Check whether an output schema exists, and whether your client validates against it.
• Do not rely on annotations to decide what is safe.
• Compare the live list with the directory profile. Our MCP directory records the main tools of each listed server, so a tool you do not recognise, especially after an update, is worth a look.
• Check that your client shows tool inputs before calls and logs usage.

What this is not

This is a reading of one specification page, not a review of any server. Revision 2026-07-28 may differ from the revision your tools use; see what changed in the 2026-07-28 revision and our overview, What is MCP. Accounts and planned features here are not open yet; see what is planned.