# How to write MCP tool descriptions that agents call

> Agents find MCP tools by searching names and descriptions, then decide whether to call yours or use a built-in tool instead. These rules come from our runs of Claude Code and Codex against real servers, from the agents’ own limits that m3 lint checks, and from the Claude, OpenAI, and Muse directory review rules.

Facts last checked: 2026-11-17.

## Short answer

Write each MCP tool so an agent can find it and call it correctly on the first try:

1. Give every tool a description that says what it does, when to use it, and its limits and side effects.
2. Put the essentials first and stay under 2,048 characters.
3. Repeat important schema constraints in plain words, and keep input schemas under 5,000 bytes.
4. Use unique snake\_case names, one operation per tool, and annotations that match behavior.
5. Make error messages say how to fix the call, and put everything the model needs in structuredContent.
6. Never steer the model with lines like "ALWAYS use this tool"; measure through each agent instead.

## What should an MCP tool description say?

Claude Code and Codex find MCP tools by searching their names and descriptions, so a tool without a description is hard to find. The OpenAI directory treats a missing description as an error, and the Claude directory warns on it.

OpenAI asks that a description explain the tool’s purpose and behavior, when to use it, and any relevant limitations or side effects. Claude asks for narrow, unambiguous language about what the tool does and when it should be invoked. Write for both: what it does, when to use it, what it will not do, and what it changes.

## How long can a tool description be?

Keep each description under 2,048 characters and put the essentials first: that is where older Claude Code versions truncate, and newer ones stop at 4,096. Server instructions are truncated the same way, and Codex sends them with every turn, so long instructions cost tokens on every call.

## Why do agents ignore parts of my input schema?

Because the model may never see them. Codex drops some JSON Schema keywords and root-level if and then conditionals, so repeat any constraint that matters in the property description. Codex also compacts input schemas over 5,000 bytes and removes descriptions first. In our tests a 14 KB schema lost its required nested fields, and the call only worked again once the schema budget was raised.

Keep schemas small and flat where you can, and keep the catalog small too: in our design study, a 70-tool catalog cost 20 to 30% more per successful task.

## How should I name tools and annotate them?

Use unique snake\_case ASCII names, avoid double underscores, and keep the full mcp\_\_server\_\_tool name within 128 characters, or 64 for older Codex versions. The Claude directory rejects names over 64 characters. Two names that differ only in punctuation, such as fetch.page and fetch\_page, misrouted a call in Claude Code in a direct probe.

Give each tool one operation rather than a catch-all with an action or method enum. Annotations must match behavior: Claude wants a title plus readOnlyHint or destructiveHint where they apply, and OpenAI wants all three hints as explicit booleans. OpenAI rejects servers whose hints "do not appear to match the tool’s behavior".

## What makes an MCP error message useful to an agent?

An error should tell the model how to fix the call, with the fix at the start. A bare 400 Bad Request gave small models nothing to retry with in our design study, while an error that named the invalid value and listed the accepted ones led the agent to retry correctly on the next call. Claude Code keeps only about the first and last 5,000 characters of an error, so long errors lose their middle.

When a result carries structuredContent, Claude Code, and Codex in direct mode, give the model that and drop the text. Put everything the model needs into the structured result.

## Should a description tell the agent to always use the tool?

No. The directories reject steering language such as "ALWAYS use this tool" or "call this FIRST", in descriptions, server instructions, and tool results alike. The temptation is real, because your server competes with the agent’s built-in tools: Codex skipped servers on 44.5% of should-call trials in our runs. The fix is a clear description and a server that answers well, then measuring how often each agent actually calls it.

Description wording alone moved results less than you might expect. Adding only a description flaw left Claude Haiku and Sonnet at 20 of 20, while silent pagination was the most damaging single flaw, and five flaws together compounded far beyond their separate effects.

## How do I check my tool descriptions?

Run m3 lint against your server’s start command or URL. It reads the tool metadata without calling a tool and flags missing or overlong descriptions, names agents will reject, schema features Codex drops, and directory rule violations. It exits non-zero on findings at or above --fail-on, so it can gate CI. It cannot judge steering language; review that by hand.

Then prove it with an agent test: run Claude Code, Codex, or OpenCode against the server and assert with to\_have\_tool\_call that the call happened.

From the directory readiness reference:

```
m3 lint --directory claude --harness claude_code -- python server.py
```

## Frequently asked questions

### How long should an MCP tool description be?

Long enough to say what the tool does, when to use it, and its limits, with the essentials first, and under 2,048 characters so no Claude Code version truncates it.

### Why does my agent call the wrong tool?

Common causes are names that differ only in punctuation, catch-all tools with an action enum, descriptions that do not say when to use the tool, and schema constraints the agent never sees. m3 lint flags most of these; an agent test confirms the fix.

### Do MCP directories check tool descriptions?

Yes. The Claude connector directory and the OpenAI plugin directory both review descriptions, names, and annotations, and both reject steering language and hidden text.

## Related

- [Pass Claude and ChatGPT MCP directory review](https://m3.sineframe.com/blog/pass-mcp-directory-review)
- [Research: Haiku vs Opus on a well-built MCP server](https://m3.sineframe.com/blog/mcp-server-design-small-models)
- [Research: Claude Code vs Codex on 10 MCP features](https://m3.sineframe.com/blog/claude-code-vs-codex-mcp)
- [Test an MCP server with Codex](https://m3.sineframe.com/mcp-testing/codex)
- [Directory readiness reference](https://m3.sineframe.com/docs/reference/directory-readiness)
