💡 Your MCP Server's Tool Descriptions Are a Prompt, Not Documentation

When an MCP server exposes ten tools with similar names and vague one-line descriptions, Claude has to guess which one fits a given request — and guesses are where wrong tool calls come from. Tool descriptions get read by the model at decision time, the same way any other prompt text does, which means they deserve the same care.

• State what the tool does AND when to use it — "searches customer records" is weaker than "searches customer records by name or email; use this before create_customer to check for duplicates."
• Disambiguate near-duplicate tools explicitly — if two tools could plausibly handle the same request, say in each one's description why you'd pick it over the other.
• Document side effects in the description, not just the schema — "this permanently deletes the record" belongs in the text Claude reads before calling it, not buried in a response field.

💡 A Quick Audit: Which of Your MCP Servers Can Actually Write?

As MCP servers accumulate across a team — one for the CRM, one for the ticketing system, one for internal docs — it's easy to lose track of which ones are read-only and which can mutate real data. A five-minute audit worth running periodically: list every configured MCP server, and for each, confirm explicitly whether it has write access and to what.