Each guide covers one check from the agent-readiness audit: what it means, why agents care, and the fix in TypeScript and Python. Counts are live, across the 15,312 reachable servers we audit.
Give every MCP tool an object inputSchema
Tools need an inputSchema whose root is {"type":"object"}, even when they take no arguments. 2 of 15,312 servers today.
Make "required" match "properties" in tool schemas
Every name in "required" must be declared in "properties", and "required" must be an array of strings. 6 of 15,312 servers today.
Give every tool parameter a type
Each property needs type, enum, anyOf/oneOf or $ref. 268 of 15,312 servers today.
Models choose tools almost entirely from the description. A tool without one is rarely picked, or picked for the wrong job. 15 of 15,312 servers today.
Write tool descriptions that say when to use the tool
Descriptions under 20 characters usually restate the name. Add when to use it and what it returns. 354 of 15,312 servers today.
Describe every tool parameter, with format and an example
Parameters without a description are the commonest cause of wrong arguments on the first call. 5,915 of 15,312 servers today.
Make sibling tool descriptions distinct
Tools on one server with identical descriptions get picked at random. 2,440 of 15,312 servers today.
Add readOnlyHint and destructiveHint annotations to MCP tools
Annotations tell clients which tools are safe to auto-approve and which need the user's confirmation. 6,545 of 15,312 servers today.
Mark tools that change state as destructive
Tools named create/send/delete/pay… should declare readOnlyHint: false and a destructiveHint. 1,775 of 15,312 servers today.
Tool descriptions that trip tool-poisoning scanners
Hidden instructions, telling the model to avoid other tools, or asking it to read config files look like tool poisoning, even when harmless. 38 of 15,312 servers today.
Reduce the token cost of your MCP tool list
Every connected server's full tool list is sent to the model on every request. Large catalogs cost agents money and accuracy. 1,534 of 15,312 servers today.
Trim oversized tool definitions
A few tools with very long descriptions or schemas often account for most of a server's token cost. 866 of 15,312 servers today.
Too many tools on one MCP server
Tool-selection accuracy drops as the menu grows, and some clients cap active tools. 1,859 of 15,312 servers today.
MCP tool names: allowed characters and length
Tool names should be 1–128 characters of A–Z, a–z, 0–9, underscore, hyphen and dot. 2 of 15,312 servers today.
Make MCP tool names work with OpenAI-style function calling
OpenAI-compatible function calling only accepts ^[a-zA-Z0-9_-]{1,64}$. Dots and names over 64 characters get renamed or dropped. 116 of 15,312 servers today.
Duplicate tool names on one MCP server
Two tools with the same name: clients keep one and silently drop the other.
Declare an outputSchema for structured tool results
Since the 2025-06-18 spec, tools can declare an outputSchema and return structuredContent that clients validate. 10,401 of 15,312 servers today.
Upgrade your MCP SDK to a current protocol revision
Servers that only speak 2024-11-05 miss structured output, annotations, elicitation and the current auth model. 3,250 of 15,312 servers today.
Move from the legacy HTTP+SSE transport to Streamable HTTP
The two-endpoint HTTP+SSE transport was deprecated in the 2025-03-26 spec in favour of Streamable HTTP. 3 of 15,312 servers today.
Validate the Origin header on your MCP server
A local or intranet MCP server that accepts any Origin can be driven by a web page through DNS rebinding.
Publish OAuth metadata so MCP clients can sign in
Remote clients find your authorization server through RFC 9728 protected-resource metadata and RFC 8414 server metadata.
Support dynamic client registration for MCP clients
Clients that have never seen your server register themselves (RFC 7591) or use a client ID metadata document.
Your MCP server is listed but unreachable
The registry endpoint did not complete an initialize handshake.
Removing or changing MCP tools breaks agents that depend on them
Tools removed or whose schemas changed in the last 30 days break saved workflows and agent memory. 7,195 of 15,312 servers today.