Building an MCP server means writing tool definitions a model has to interpret correctly with zero back-and-forth clarification, which makes the naming, description and error-message writing a distinct discipline from the underlying server logic, and one that determines whether the whole server actually works reliably in practice.
Naming: specific beats clever
This is a different concern from the broader question of whether a function should be exposed as a resource or a tool in the first place. Assuming that split is already right, this is specifically about making whichever one you've built legible and unambiguous to the model calling it, which is its own separate craft worth getting right.
A quick internal test before shipping any new tool: have someone unfamiliar with the build read just the name and description and guess what it does and when they'd use it. If their guess is wrong or vague, the description needs work before the tool goes anywhere near production.
A tool name should describe exactly what it does in terms a model, and a human skimming a list of available tools, immediately understands. Generic names like "process" or "handle" force the model to infer intent from context that may not be there. Specific names like "approve_leave_request" or "generate_weekly_variance_report" carry meaning on their own, without needing the description to do all the disambiguation work.
Names: specific and action-oriented, not generic verbs
Descriptions: state what it does, when to use it, and what it returns
Parameters: names matching how a person would naturally describe the input
Errors: plain-language explanations, not raw exception text or stack traces
Descriptions: the part most teams under-invest in
A one-line description that's technically accurate but vague, "updates a record," leaves genuine ambiguity about which record, under what conditions, with what side effects. A stronger description states the scope explicitly: what type of record, what fields change, whether the action is reversible, and any constraints on when it should be called. This is the same discipline that makes a good API endpoint's documentation useful versus useless, applied to a context where the reader is a model rather than a human developer reading a spec.
Error messages: the most commonly neglected part
When a tool call fails, whether from bad input, a downstream system being unavailable, or a permission issue, the error message needs to explain what actually went wrong in language a model can act on, not a raw exception passed straight through from the underlying system. "Invalid input: expected a date in YYYY-MM-DD format, got 'next Tuesday'" lets the model retry correctly. A bare stack trace doesn't. This is different from a broader error-envelope specification governing overall response structure; this is specifically about what the error message itself says.
A worked before-and-after
A Perth logistics business's first MCP server version had a tool called "update" with the description "updates shipment data" and errors that passed through raw database exceptions. Testing showed the model calling it incorrectly on roughly a third of attempts and unable to recover cleanly from any failure. Renaming it to "update_shipment_status", writing a description naming the exact fields it touches and the valid status values, and rewriting error messages in plain language, cut the incorrect-call rate to near zero and let the model successfully retry after most failures without a human needing to intervene.
What getting this right is worth
For the Perth logistics business above, the redesign took roughly a day and a half of a developer's time, worth around $1,200 at typical contractor rates, and it avoided what would otherwise have become a recurring support burden as more staff started relying on the server for daily shipment updates. For any Australian business building internal MCP infrastructure, whether in Sydney, Melbourne or a regional hub, this design pass is worth budgeting into the project from the outset, not treated as an afterthought once something's already gone wrong in production.
None of this requires deep technical sophistication, just the discipline of writing for the actual reader, a model with no other context than what's in front of it, rather than for a human developer who already understands the system.
Treat the writing itself, not just the underlying logic, as part of the engineering work, and budget time for it accordingly on every tool built, not just the ones that end up causing visible problems.
It costs almost nothing to run and catches exactly the ambiguity that would otherwise show up as a wrong call in production.
Run it on every tool before it ships, not just the ones that already caused a problem.
It's the cheapest reliability improvement available before a server goes live.
