# MCP tool descriptions agents choose > For the complete documentation index, see [llms.txt](https://workpods.ai/llms.txt) MCP tool descriptions are the text an AI agent reads to decide whether to call your tool, what to pass and what to expect back. Say what the tool does, when to use it and what comes back, and set annotations that tell the truth about side effects, because ChatGPT, Claude and directory reviewers all read them. ## What does an agent see in an MCP tool? An agent sees each tool's name, description, input schema and annotations, and never its output schema. So the description has to say what the result contains, or the model guesses from the first answer it gets. Directories show the same words on your listing page, so a tool description doubles as listing copy. Write it for the model first and the listing will read well too. ## How do I write a good MCP tool description? A good MCP tool description names the job, gives the trigger, then lists the result's fields. Compare a vague description with the start of our main tool's: ```text Vague check_site Checks a website. Ours seo_audit_page SEO audit of one web page, covering technical SEO and AI search readiness. It checks indexing (status, robots, canonical), title and meta description, headings, schema markup, links, image alt text and AI readiness. Use it when the person asks for an SEO or website audit of a page, or what to fix first. result has url, status, scores (passed and judged checks per layer), problems (each with check id, severity, summary and evidence) and passed. Results are cached for 15 minutes. ``` Every one of ours follows the same order: what it does in one sentence, when to use it, what it needs and its limits, what comes back field by field, and how paging works if it pages. They run from about 100 to 220 words, and our tests fail any tool whose description is under 200 characters. Say what `null` means as well. "null when the registry could not be read, an empty list when nothing is listed" leads the model to two different answers, which is what you want. ## How should MCP tools be named? Name each tool after the job a person asks for, in their words. We renamed ours in November 2026 so the names match requests: `seo_audit_page` answers "audit this page", `check_ai_crawler_access` answers "can AI crawlers read this page?", and `draft_llms_txt` answers "write me an llms.txt". When two tools share a job, say how they connect: "It returns at once with jobId; call get_site_crawl with it every 20 to 30 seconds until status is done." ## How do MCP tool annotations work? MCP tool annotations are three hints, `readOnlyHint`, `destructiveHint` and `openWorldHint`, that tell a client whether a tool changes anything, can destroy anything, and reaches systems outside your server. Set all three as explicit booleans on every tool, because ChatGPT's and Claude's directories read them and flag any that don't match what the tool does. ```ts // Changes nothing anywhere: the checks. const READ_ONLY = { readOnlyHint: true, destructiveHint: false, openWorldHint: true } as const // Starts a background job, sends a request or saves a public page. const WRITES = { readOnlyHint: false, destructiveHint: false, openWorldHint: true } as const ``` A tool is read-only only if it writes nothing, sends no messages, stores no files and starts no jobs. We first marked our site crawl read-only; OpenAI's guidelines count starting a job as a change, so we switched it, and Claude's portal relabelled the tool from "Read-only" to "Writes". ## What did ChatGPT's scan flag in our tools? ChatGPT's tool scan flagged six of our checks: "This tool is marked readOnlyHint: true, but its behavior appears to have a user-visible side effect." Each check saved its result as a shareable report page for 30 days, and the scan counted that saved page as a side effect. We changed the tools to match. The checks now save nothing and return a `resultId`, and a new tool, `share_report`, saves the report only when the person asks for a link. ```text Before seo_audit_page readOnlyHint: true saves a report page on every call -> flagged After seo_audit_page readOnlyHint: true returns a resultId, saves nothing share_report readOnlyHint: false saves the report page when asked openWorldHint: true the page is public to anyone with the link ``` Our first version of `share_report` had `openWorldHint: false`, and the scan flagged that too, since a public page reaches the open web. With both fixed, the next scan read "No findings in the latest MCP scan". Our server now has 13 tools, and our tests assert that exactly three are not read-only: the crawl, the audit request and `share_report`. ## Which words get MCP tools flagged? Leave other AI assistants' names out of plugin-level text, leave out pricing words such as "free", and never put instructions to the model in a description. ChatGPT's automated check flagged our first plugin description for naming other assistants, and OpenAI's guidelines bar pricing and promotions in descriptions. Claude's checklist also asks you to confirm that descriptions carry no instructions about other tools and no hidden text. We renamed `request_free_audit` to `request_full_audit` and stopped returning a promotional link in results for the same reason. The review steps are in Part 1, on the [Claude connector directory](https://workpods.ai/guides/mcp-distribution/claude-connector-directory), and Part 2, on the [ChatGPT apps directory](https://workpods.ai/guides/mcp-distribution/chatgpt-apps-directory). ## How are MCP tool descriptions scored? Quality checkers read your tools the way an agent does and score how complete the descriptions are. Manufact scored our tool documentation 82 out of 100, alongside 100 for protocol and tools. Most of the rest of our score came from server metadata, which took us from 68 to 83 overall; see Part 5, on [MCP server metadata](https://workpods.ai/guides/mcp-distribution/mcp-server-metadata). Before you submit anywhere, run this checklist on every tool: ```text [ ] Name says the job in the user's words [ ] First sentence says what it does; the next says when to use it [ ] Every input: meaning, format, allowed values, default [ ] What comes back, field by field, including null and empty [ ] readOnlyHint, destructiveHint and openWorldHint set, and true to what the tool does [ ] annotations.title set (Claude's directory shows it as the display name) [ ] No other assistants named, no pricing words, no instructions to the model ``` The whole series is ranked in [MCP servers for SEO and GEO](https://workpods.ai/guides/mcp-distribution). You can try our tools by connecting the server on the [Agent Ready](https://workpods.ai/tools/agent-ready) page, and we write and review tool descriptions for clients as part of our [agent platform listing work](https://workpods.ai/axo/agent-platforms). ## Sources - Scan findings: the MCP scan in OpenAI's plugin portal for our server, 12 to 13 November 2026. - Tool documentation score: our Manufact leaderboard page, 11 November 2026. - Review rules: OpenAI's plugin guidelines and the Claude directory submission checklist, November 2026. ## Questions buyers ask ### What should an MCP tool description include? What the tool does, when to use it, how its inputs combine and what comes back, including what null or an empty list means. Agents never see output schemas, so the result has to be described in words. ### When should readOnlyHint be false? Whenever the tool changes something: writing data, sending a message, saving a file or page, or starting or queuing a job. Saving a shareable report counts. ### What does openWorldHint mean? It says whether a tool reaches systems outside your server, such as public websites. A tool that fetches pages, sends a request elsewhere or publishes a public page should set it to true. ### Does Claude use annotations.title? Yes. Claude's directory shows a tool's `annotations.title` as its display name, so set it on every tool. By Prateek Tomar · Reviewed by Shefali Munjal · Published 2026-11-12 --- Source: https://workpods.ai/guides/mcp-distribution/mcp-tool-descriptions · WorkPods.ai, updated 2026-11-12