What MCP Taught Me About Tool Design
Summer 2026 · ~3 min read
Building an MCP (Model Context Protocol) integration at GoDaddy this summer meant designing an interface where the primary caller wasn't a person clicking through a UI or even another service following a fixed code path — it was an AI agent deciding, at runtime, whether and how to call the tool at all. That reframes almost every API design instinct I had.
The name and description are load-bearing
A human reading slightly-off documentation will usually push through it — check a Slack channel, ask a teammate, infer from context. An agent deciding whether to invoke a tool is working from the tool's name and description in that moment, with no side channel to check. Vague naming that a human would shrug off becomes a real failure mode: the tool gets called wrong, or not called when it should be.
Errors have to be self-explanatory, because there's no one to ask
A human hitting a cryptic error can go find out what it means. An agent mostly can't — it has the error text and whatever it does next has to be inferable from that text alone. That pushed me toward writing error messages that read like short instructions ("missing required field `index_name` — pass one of: ...") rather than the terse, log-line-style errors I'd normally write for a human debugging with the source code open.
Narrow and composable beats broad and clever
It's tempting to build one flexible, do-everything tool. In practice, a small set of narrow, predictable tools was easier for the agent to use correctly and easier for me to reason about and test — the same lesson as good Unix tool design, just rediscovered from a different direction.
The takeaway
Designing for an agent as the caller is, in a strange way, a forcing function for better API design generally — it punishes ambiguity that a human caller would have quietly absorbed. I've started applying the same bar (self-explanatory names, self-explanatory errors, narrow scope) to APIs meant for humans too, and they've gotten better for it.