Your Tool Description Is a Prompt (And You're Writing It Like a JIRA Ticket)
· 9 min read
Here is a tool description from a real, public MCP server. The name has been changed because I'm not in the business of public shaming, but the wording is verbatim:
query_data: Queries the data.
Two words. One of which is the tool's own name. The other a tautology. This is what happens when a developer treats description as a field on a struct rather than what it actually is: a prompt fragment that the AI reads to decide whether to call your tool.
If you are writing tool descriptions the way you write Swagger comments, you are writing them wrong. Let's talk about why.