One post tagged with "tool-design"

Your Tool Description Is a Prompt (And You're Writing It Like a JIRA Ticket)

May 22, 2026 · 18 min read

MCP Developer & Educator

Series cover. A bad description reading query_data: queries the data is marked as a tautology in red, next to a useful one that says search orders by status and date and adds when to use it, its inputs and its boundaries. The strapline reads: the model reads every word.

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 unchanged:

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.