# 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.

Published 2026-11-19 by mcp.tc. Canonical: https://mcp.tc/blog/write-mcp-tool-descriptions

**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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools) defines a tool as `name`, optional `title`, `description`, optional `icons`, `inputSchema`, optional `outputSchema` and optional `annotations`. The [schema reference](https://modelcontextprotocol.io/specification/2026-07-28/schema) 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](https://docs.aws.amazon.com/prescriptive-guidance/latest/mcp-strategies/mcp-tool-strategy-definitions.html) 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](https://modelcontextprotocol.io/specification/2026-07-28/server/tools), 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](https://www.anthropic.com/engineering/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](https://arxiv.org/html/2602.18914v1), 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:

```text
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](https://ts.sdk.modelcontextprotocol.io/v2/servers/tools)), `registerTool` takes a name, a config and a handler:

```ts
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](https://py.sdk.modelcontextprotocol.io/servers/tools/)), the docstring becomes the description, the function name becomes the tool name, and `Field(description=...)` documents each argument:

```python
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](https://modelcontextprotocol.io/specification/2026-07-28/schema) 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](https://modelcontextprotocol.io/specification/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](https://py.sdk.modelcontextprotocol.io/servers/structured-output/) 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](https://mcp.tc/blog/mcp-tool-annotations) covers the four hints in detail.

`instructions` come back from [`server/discover`](https://modelcontextprotocol.io/specification/2026-07-28/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](https://mcp.tc/blog/debug-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](https://mcp.tc/cli):

```bash
npx mcp-tc check https://mcp.example.com/mcp
```

It 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](https://mcp.tc/docs/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](https://mcp.tc/i/mcp-tc#history) shows the format, and the [recent changes page](https://mcp.tc/changes) 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 check` against your endpoint before and after a description change, or `npx mcp-tc create my-server` to start a new project whose default template is a Streamable HTTP server on Express with a stateless `/mcp` endpoint and a server card.
- [Suggest your server](https://mcp.tc/submit) once the descriptions read well; the listing is built from a live handshake and `tools/list` read, 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](https://mcp.tc/docs/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

- <https://modelcontextprotocol.io/specification/2026-07-28/server/tools>
- <https://modelcontextprotocol.io/specification/2026-07-28/schema>
- <https://modelcontextprotocol.io/specification/2026-07-28/server/discover>
- <https://modelcontextprotocol.io/specification/2026-07-28/changelog>
- <https://www.anthropic.com/engineering/writing-tools-for-agents>
- <https://ts.sdk.modelcontextprotocol.io/v2/servers/tools>
- <https://py.sdk.modelcontextprotocol.io/servers/tools/>
- <https://py.sdk.modelcontextprotocol.io/servers/structured-output/>
- <https://docs.aws.amazon.com/prescriptive-guidance/latest/mcp-strategies/mcp-tool-strategy-definitions.html>
- <https://arxiv.org/html/2602.18914v1>
- <https://github.com/mcptc/mcp-tc>
