How to Write MCP Tool Descriptions and Schemas That Work
Write MCP tool descriptions models use correctly: names, parameter descriptions, enums, output schemas, annotations and server instructions, with SDK syntax.
Cet article est en anglais.
TL;DR. A model chooses and calls a tool from text: the tool name, its description, the per-parameter descriptions inside inputSchema, and the server's instructions. The 2026-07-28 specification says the description "can be thought of like a 'hint' to the model", so write MCP tool descriptions the way you would brief a new teammate: what the tool does, when to use it instead of a neighbor, what it returns, and what fails. Put constraints in the schema (enums, defaults, required), declare an outputSchema when the output has a fixed shape, and test with real tasks before you publish. Once a server is listed on mcp.tc, the changes its checks find in that text go on the listing's History tab, so treat descriptions as part of the interface.
What does the model see in an MCP tool definition?
A model sees a tool's name, its description, and the inputSchema with each parameter's description, plus the server's instructions when the client adds them to the system prompt. The title, icons and annotations are for the client's interface and approval logic, and outputSchema exists for validation on both sides.
The 2026-07-28 tools specification defines a tool as name, optional title, description, optional icons, inputSchema, optional outputSchema and optional annotations. The schema reference describes description as "a human-readable description of the tool" that "can be used by clients to improve the LLM's understanding of available tools" and "can be thought of like a 'hint' to the model."
| Field | Who reads it | What it is for |
|---|---|---|
name | model, client, logs | Identifier, unique within the server |
title | people | Display name; precedence is title, then annotations.title, then name |
description | model | The hint that drives tool selection |
inputSchema | model, validator | Parameter names, types, descriptions, enums, defaults, required |
outputSchema | validator, model | Shape of structuredContent |
annotations | client | Behavior hints such as readOnlyHint, untrusted unless the server is trusted |
instructions (server level) | model | Guidance about the server as a whole, returned by server/discover |
Tool definitions travel with the prompt. AWS's guidance on tool definitions notes that they are "included in the LLM prompt on each invocation, consuming context window space alongside system instructions and conversation history." The specification adds that servers "SHOULD return tools in a deterministic order", because stable ordering "improves LLM prompt cache hit rates when tools are included in model context." A list that reshuffles on every request costs tokens on every turn.
How should I name MCP tools and parameters?
Tool names in MCP should be 1 to 128 characters of ASCII letters, digits, underscore, hyphen and dot, unique within the server, and readable as a verb plus an object, so the model knows what a tool does before it opens the description. Parameter names should say what kind of value they take.
The length and character rules are the specification's own, under Tool Names, along with "SHOULD NOT contain spaces, commas, or other special characters." The same section notes that uniqueness is scoped to one server: clients that aggregate several servers "MAY encounter naming collisions (for example, two servers each exposing a search tool)" and should prefix names with a server identifier. You can prefix yourself. Anthropic's Writing tools for agents (11 September 2025) recommends grouping related tools under a shared prefix, by service or by resource, and reports that prefix versus suffix placement changed evaluation results, so choose a scheme by testing it.
For parameters, the same post gives the rule in one line: "instead of a parameter named user, try a parameter named user_id." A February 2026 arXiv study, From Docs to Descriptions, analyzed 10,831 MCP servers and found that the most frequent defect in its corpus was repeated tool names, in 7,894 cases (about 73%). Names are also the hardest field to change later, because every client config and every saved prompt that mentions them stops working.
What goes into an MCP tool description?
An MCP tool description should state what the tool does, when to use it instead of a neighboring tool, what it returns and what fails, in a few plain sentences a new teammate could act on without reading the code. It should not repeat the parameter list, which belongs in inputSchema, or restate the server's instructions.
The "new teammate" test comes from Anthropic's post: "think of how you would describe your tool to a new hire on your team", and make implicit context explicit. The post also observes that "even small refinements to tool descriptions can yield dramatic improvements." AWS's guidance lists the components: the tool's purpose, when to use it (user intent patterns), the context of the output, parameters, and error conditions. It also asks you to document prerequisites and follow-up actions.
The specification gives one concrete example of what belongs in a description. Its non-normative section on stateful tools says a server's retention policy "should be stated in the creation tool's description (e.g., 'baskets expire after 24 hours of inactivity') so the model can see it when deciding to create state."
A before and after, for a generic catalog server:
Before:
Search products.
After:
Find products in the catalog whose name contains `query`. Returns up to
`limit` matches with `id`, `name` and `price`. When you already have an
`id`, call `catalog_get` instead. Matching is case-insensitive; no match
returns an empty list, not an error.The arXiv study measured which parts of a description move tool selection for its test model. Describing functionality had the largest effect (+11.6% on selection probability in the paper's figures), then accuracy (+8.8%), completeness (+5.9%) and conciseness (+1.5%). In its five-server experiment, a description that met its full standard was selected 72% of the time on average against a 20% uniform baseline. One model and one benchmark, but the ordering matches the practitioner advice: say what the tool does first, then be correct, then be complete, then be short.
How do I write inputSchema parameter descriptions, enums and defaults?
Every parameter in an MCP inputSchema needs its own description, because the schema is the only place the model learns what a value means. Constraints belong in JSON Schema keywords such as enum, default, minimum, maximum and required rather than in prose, and free-form values get an example instead of an enum.
The TypeScript SDK v2 docs say a .describe() call on a Zod field "survives the conversion" to JSON Schema and is "the only documentation the model gets for that argument." AWS's guidance adds the enum rule: enums "work best for finite sets, such as status or priority values, but are not suitable for free-form text, dynamic values, arbitrary numbers, or resource identifiers. In those cases, provide clear descriptions and examples instead." It also recommends a default "when possible so the LLM does not have to guess."
In the TypeScript SDK v2 (servers/tools), registerTool takes a name, a config and a handler:
import { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';
server.registerTool(
'catalog_search',
{
title: 'Search the catalog',
description:
'Find products in the catalog whose name contains `query`. Returns up to `limit` matches with id, name and price. When you already have an id, call catalog_get instead.',
inputSchema: z.object({
query: z.string().describe('Substring to match against product names'),
limit: z.number().int().min(1).max(50).default(10).describe('Maximum number of results'),
}),
outputSchema: z.object({
products: z.array(z.object({ id: z.string(), name: z.string(), price: z.number() })),
}),
annotations: { readOnlyHint: true, openWorldHint: false },
},
async ({ query, limit }) => {
const output = { products: await search(query, limit) };
return {
content: [{ type: 'text', text: JSON.stringify(output) }],
structuredContent: output,
};
},
);In the Python SDK (servers/tools), the docstring becomes the description, the function name becomes the tool name, and Field(description=...) documents each argument:
from typing import Annotated
from pydantic import BaseModel, Field
from mcp.server import MCPServer
from mcp.types import ToolAnnotations
mcp = MCPServer("catalog")
class Product(BaseModel):
id: str
name: str
price: float
@mcp.tool(
title="Search the catalog",
annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
)
def catalog_search(
query: Annotated[str, Field(description="Substring to match against product names.")],
limit: Annotated[int, Field(ge=1, le=50, description="Maximum number of results.")] = 10,
) -> list[Product]:
"""Find products in the catalog whose name contains `query`.
Returns up to `limit` matches with id, name and price. When you already
have an id, call catalog_get instead.
"""
...Two schema rules from the specification come up often. When you use composition keywords such as oneOf, the schema reference says to "declare properties at the schema root and keep the branches to presence assertions such as required", because type constraints inside a oneOf branch "are not enforced for whichever branch does not match." And the x-mcp-header extension, which mirrors a parameter into an HTTP header, carries a warning: "Server developers SHOULD NOT mark sensitive parameters (passwords, API keys, tokens, PII) with x-mcp-header, as header values are visible to network intermediaries." For a tool with no parameters, the recommended schema is { "type": "object", "additionalProperties": false }.
When should a tool declare an outputSchema?
A tool should declare an outputSchema when it returns data with a fixed shape that the model or a follow-up call will read, such as records with IDs, and skip it for prose, images or results whose shape varies. With a schema declared, the server must return matching structuredContent and should still include the JSON as text.
The rules are in the specification: "Servers MUST provide structured results that conform to this schema" and "Clients SHOULD validate structured results against this schema." For older clients, "a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block." The 2026-07-28 changelog loosened outputSchema to "any JSON Schema 2020-12 keywords" and structuredContent to "any JSON value", so an array at the root is allowed.
Both SDKs enforce the contract. The TypeScript SDK "validates structuredContent against outputSchema before the result leaves your server" and advertises the derived JSON Schema in tools/list. The Python SDK's structured output page derives the schema from the return annotation: a BaseModel, TypedDict or dataclass becomes an object schema, scalars and lists (like the list[Product] above) are wrapped under a result key, and structured_output=False turns the schema off. A mismatched return value reaches the client as is_error=True.
Describe output fields as well (the specification's own example labels temperature as "Temperature in celsius"), and plan for size. Anthropic's post suggests a response_format enum with concise and detailed values, where detailed responses include the IDs needed for follow-up calls and concise ones omit them and use about a third of the tokens. It also reports that resolving UUIDs to readable names reduced hallucinations in retrieval tasks.
Error text is part of output design. The specification separates protocol errors (unknown tool, malformed request) from tool execution errors, which "contain actionable feedback that language models can use to self-correct and retry with adjusted parameters" and travel in the result with isError: true. Its example message is the pattern to copy: "Invalid departure date: must be in the future. Current date is 08/08/2025."
What do annotations and server instructions add?
MCP tool annotations tell the client, not the model, how a tool behaves: readOnlyHint (default false), destructiveHint (default true), idempotentHint (default false) and openWorldHint (default true). Server instructions are a short note about the server as a whole that a client may place in the system prompt.
The schema reference states that "all properties in ToolAnnotations are hints" and that "Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers." The tools page makes it a requirement: clients "MUST consider tool annotations to be untrusted unless they come from trusted servers." Set them accurately, and never use them in place of a clear description. The Python docs note that destructive_hint and idempotent_hint apply only to tools that write. The earlier post on MCP tool annotations covers the four hints in detail.
instructions come back from server/discover alongside supportedVersions and capabilities. The schema says they "should focus on information that helps the model use the server effectively and should not duplicate information already in tool descriptions." Good uses: the order in which tools are usually called, ID formats and units shared across tools, rate limits, and what the server cannot do. If a sentence applies to one tool, it belongs in that tool's description.
How do I test MCP tool descriptions before publishing?
Testing MCP tool descriptions means reading the exact tools/list output a client will see, running a handful of realistic multi-step tasks that each have a verifiable outcome, and counting wrong tool choices, retries and tokens. Change one description at a time, rerun the same tasks, and keep the wording that wins.
Anthropic's post describes that loop: realistic tasks rather than sandbox prompts, each "paired with a verifiable response or outcome", verifiers that tolerate formatting differences, metrics such as runtime, tool call counts, token use and tool errors, and a held-out set so you do not overfit to your own wording.
To see what the model sees, dump tools/list with MCP Inspector or curl; the post on debugging an MCP server walks through both. For a review against the same checks mcp.tc runs when it lists a server, use the mcp-tc command-line tool:
npx mcp-tc check https://mcp.example.com/mcpIt tests the handshake in both protocol styles, server/discover and initialize, reads tools/list, then prints errors, warnings and suggestions. Among the things it flags are tool descriptions under 20 characters, tools without readOnlyHint, and tools that may change things but have no destructiveHint. The exit code is 0 with no errors, 6 when it found errors, and 5 when the server could not be read at all. For a local server, --stdio starts the project's own server and --command "<command>" starts any other. It needs Node.js 20 or later, runs on your machine, and does not predict whether a server will be listed.
What happens to tool descriptions after the server is listed?
After a server is listed on mcp.tc, its tool text is compared over time: every 3 hours mcp.tc reads the tool list of each listing it can read without signing in, and a changed description, parameter description, title, schema, hint or server instruction goes on the listing's History tab with the date and time.
On 18 November 2026 the directory held 1,552 approved listings, 551 of which had a tool list that mcp.tc compares every 3 hours; the change history began on 6 October 2026. The docs on changes list what counts: tools added or removed (a rename shows as one removal and one addition), new descriptions or titles, parameters added, removed or newly required, new parameter descriptions, new input or output schemas, flipped hints, invisible characters such as zero-width or text-direction marks in a tool's text, and new server instructions. A change is recorded only after two reads agree, and a listing's first read is its baseline. New versions are recorded too, at most one a day.
For a server author this means a description edit is visible, with the text before and after, to anyone who opens the listing's History tab or follows it, and followers get an email when mcp.tc's checks find a change (as changes happen, at most one email an hour, or as a daily summary). mcp.tc's own server is a listing like any other; its History tab shows the format, and the recent changes page lists the newest changes across the directory.
The limits matter as much as the coverage. The reads are made without signing in, so tools shown only after sign-in or only to certain clients are not watched, local servers without a bundle manifest have no watched tool list, and a change undone between two checks can be missed. The History is not a security review and rates nothing. It helps readers notice that text changed, which is a good reason to add a line to your own changelog when you rewrite a description on purpose.
What you can do next on mcp.tc
On mcp.tc you can check a server the way the directory reads it, suggest it for listing, claim and edit its listing, and follow the servers your own tools depend on, all without the directory ever sitting between your clients and the server.
- Run
npx mcp-tc checkagainst your endpoint before and after a description change, ornpx mcp-tc create my-serverto start a new project whose default template is a Streamable HTTP server on Express with a stateless/mcpendpoint and a server card. - Suggest your server once the descriptions read well; the listing is built from a live handshake and
tools/listread, so the text you ship is the text readers see. - Claim the listing and edit its descriptions, category, tags and setup notes, as described in the docs for server owners; owner edits go live at once and appear in the History labeled "Server owner".
- Follow the listings you depend on, so a rewritten description or a newly required parameter in a server you call reaches your inbox.
FAQ
How long should an MCP tool description be?
Long enough to say what the tool does, when to use it over a neighboring tool, what it returns and what fails; usually two to five sentences. The 2026-07-28 specification sets no length limit, but tool definitions are sent with the prompt on every turn, so each extra sentence costs tokens on every call. Move parameter details into inputSchema descriptions and server-wide notes into instructions, then test whether a shorter version is still selected correctly.
Does the model see the tool title or the annotations?
Usually not. In the 2026-07-28 specification, title is "intended for UI and end-user contexts", and annotations such as readOnlyHint are hints for the client, which must treat them as untrusted unless the server is trusted. What the model reads is name, description, the parameter descriptions in inputSchema and, if the client includes them, the server's instructions. If a fact matters to tool selection, put it in the description.
Should every MCP tool declare an outputSchema?
No. Declare one when the output has a fixed shape that the model or another tool will read, such as records with IDs, and skip it for prose, images or variable results. When a schema exists, the server must return conforming structuredContent, clients should validate it, and the server should still include the JSON as a text block for older clients. Both official SDKs validate the result before it leaves the server.
Can I put model guidance in server instructions instead of each tool?
Only guidance that applies to the server as a whole. The specification says instructions "should not duplicate information already in tool descriptions" and should help the model use the server effectively. Shared ID formats, units, call order and limits fit there. Anything about one tool belongs in that tool's description, because a client may not add instructions to the system prompt at all, while tool descriptions always arrive with the tool list.
How do I know when a server's tool descriptions change?
Read tools/list and compare it with a saved copy, or follow the server's listing on mcp.tc. Every 3 hours mcp.tc reads the tool list of each listing it can read without signing in, records changed descriptions, parameter descriptions, schemas and hints on the listing's History tab once two reads agree, and emails followers. It cannot see tools shown only after sign-in, and a change undone between two checks can be missed.
Sources
- modelcontextprotocol.io/specification/2026-07-28/server/tools
- modelcontextprotocol.io/specification/2026-07-28/schema
- modelcontextprotocol.io/specification/2026-07-28/server/discover
- modelcontextprotocol.io/specification/2026-07-28/changelog
- www.anthropic.com/engineering/writing-tools-for-agents
- ts.sdk.modelcontextprotocol.io/v2/servers/tools
- py.sdk.modelcontextprotocol.io/servers/tools/
- py.sdk.modelcontextprotocol.io/servers/structured-output/
- docs.aws.amazon.com/prescriptive-guidance/latest/mcp-strategies/mcp-tool-strategy-definitions.html
- arxiv.org/html/2602.18914v1
- github.com/mcptc/mcp-tc