Easiest way to hold description edits to code review is a routing test: a few dozen fixed prompts, each tagged with the tool it should land on, run on every PR that touches a description. One edited "NOT for" line can quietly move traffic from search_errors to search_logs, and that suite catches it before a host does.
Funny thing : "traditional API" was already misused before AI in a lot of cases : CRUD endpoints were ok for... CRUD apps ! For complex business workflows, the guys in the DDD community were already advocating having one endpoint for one job, with the orchestration happening in the backend, instead of leaking business workflows - and a bit of rules as well - in the client !
Clearly specifying the next steps, errors etc was also already a recommended practice in api pre-ai, with HATEOAS - the last floor of the REST pyramid, again to avoid letting business workflow decisions in the client (but I have to admit, it was a bit cumbersome pre AI)
So basically, my personal point of view on this is : we should use the same best practices as APIs for MCPs, it is just that we were skipping them for APIs as 1. it was cumbersome, and 2. we had deterministic code in the client, developed by humans with memory, so leaking a bit of business logic in the client was fine. Now that clients are agents that don't know business logic at all, we have to respect these practices !
On "Errors", I want to highlight that adding business logic validation at the tool call level instead of depending only on argument checks prevents many incorrect paths and guides the AI toward the right direction.
"Jobs instead of endpoints" is the part I'd underline. A server that mirrors the API one call per endpoint leaves the model to work out the order of operations on its own, and that's usually where it starts guessing. When a job needs three calls underneath, do you expose it as one tool, or keep the pieces and describe the sequence in the tool descriptions?
Claude Code plans my morning from TickTick, Slack and Shortcut, so I'm on the agent side of this every day. One thing I'd add to the checklist: make read versus write explicit per tool. I give agents production read-only and staging read-write, and that only works when the server lets me split it. Do any of the examples you picked do that well?
Easiest way to hold description edits to code review is a routing test: a few dozen fixed prompts, each tagged with the tool it should land on, run on every PR that touches a description. One edited "NOT for" line can quietly move traffic from search_errors to search_logs, and that suite catches it before a host does.
makes sense! evals, even small, are almost always good ROI
Every real misrouting you see in production can be added to the suite as a new case, so it grows from actual failures.
Awesome article, as always, and very useful !
Funny thing : "traditional API" was already misused before AI in a lot of cases : CRUD endpoints were ok for... CRUD apps ! For complex business workflows, the guys in the DDD community were already advocating having one endpoint for one job, with the orchestration happening in the backend, instead of leaking business workflows - and a bit of rules as well - in the client !
Clearly specifying the next steps, errors etc was also already a recommended practice in api pre-ai, with HATEOAS - the last floor of the REST pyramid, again to avoid letting business workflow decisions in the client (but I have to admit, it was a bit cumbersome pre AI)
So basically, my personal point of view on this is : we should use the same best practices as APIs for MCPs, it is just that we were skipping them for APIs as 1. it was cumbersome, and 2. we had deterministic code in the client, developed by humans with memory, so leaking a bit of business logic in the client was fine. Now that clients are agents that don't know business logic at all, we have to respect these practices !
Great article!
On "Errors", I want to highlight that adding business logic validation at the tool call level instead of depending only on argument checks prevents many incorrect paths and guides the AI toward the right direction.
"Jobs instead of endpoints" is the part I'd underline. A server that mirrors the API one call per endpoint leaves the model to work out the order of operations on its own, and that's usually where it starts guessing. When a job needs three calls underneath, do you expose it as one tool, or keep the pieces and describe the sequence in the tool descriptions?
Claude Code plans my morning from TickTick, Slack and Shortcut, so I'm on the agent side of this every day. One thing I'd add to the checklist: make read versus write explicit per tool. I give agents production read-only and staging read-write, and that only works when the server lets me split it. Do any of the examples you picked do that well?