Designing MCP tools and servers that LLMs use well

0:00 Designing tools models use well

A server can follow the spec perfectly and still fail in the real world. The model picks the wrong tool, sends bad arguments, drowns in output, or burns through tokens. In this lesson you'll learn how to design MCP tools that models use well, even when they're mixed with other servers' tools in hosts you don't control.

0:25 Why design matters

Why does design matter once the protocol works? Because in real hosts your server competes for the model's attention with dozens of other tools you've never seen. Think of a supermarket shelf. Products with clear labels, obvious purpose and sensible packaging get picked. Products with vague names get ignored, or worse, picked by mistake. Your tool names, descriptions and output sizes are your packaging. The model is a very fast shopper who reads every label but can't ask the staff.

1:00 Workflows, names, descriptions

Start with the big idea: design for workflows, not endpoints. Don't mirror your REST API one to one. Combine the steps people actually do. Schedule campaign with a segment, channel and date beats four separate calls to create a campaign and set each field. Use specific names, prefixed when generic, like crm search contacts instead of search, because your tools will sit next to other servers' tools. And put usage rules in descriptions: when to use a tool, when not to, what to call first, the limits, and what comes back.

1:40 Inputs and outputs

Next, tight inputs and compact outputs. Use enums, formats, ranges and required fields, and describe every property. Declare an output schema and return structured content plus a text version. Include the ids the next tool will need. Offer a detail or fields option instead of always returning everything. Paginate with cursors and say so plainly, like showing twenty of three hundred and twelve. And make errors actionable, telling the model how to fix the call.

2:13 Writes and stability

For writes, accept an idempotency key, because the stateless transport re issues broken requests. Set annotations honestly, read only, destructive, idempotent and open world, so good hosts can ask for confirmation at the right moments. Return tools in a deterministic order, and keep definitions stable. Constantly changing descriptions breaks caches, and silently changing a tool's behavior after people approved it is exactly what a rug pull attack looks like.

2:43 Simple example: two 'search' tools

A simple example. Two servers are connected to the same host, and both have a tool named search. One searches support tickets, the other searches product docs. A user asks, has anyone reported the login bug. The model picks the docs search half the time. The fix takes two minutes: rename them support search tickets and docs search articles, and give each a description saying when to use it and when not to. Selection errors drop, and nothing about your code changed.

3:19 How many tools?

How many tools should you have? Remember, every tool definition takes up context in every model call. Dozens of verbose tools from several servers can eat thousands of tokens and make selection worse. Keep servers focused on one domain, use toolsets or flags so admins enable only what a team needs, and consider a few flexible, well secured tools instead of many narrow ones. Some hosts support tool search or deferred loading, but don't count on it everywhere.

3:53 Example: CRM server redesign

A worked example. An agency's CRM server started as thirty eight tools mirroring the vendor API. In testing, models made six to nine calls per question and often chose the wrong one. Version two has nine tools built around jobs, like find contacts and contact brief, which returns the profile, recent activity and open deals in one call, as a twenty line summary with ids. Writes take idempotency keys, and updating a deal stage carries a destructive hint so hosts confirm. On their evaluation set, calls per question roughly halved.

4:32 Hands-on: review checklist

The lesson includes a ten point review checklist. Run it for every tool: specific name, a description with purpose, when to use and when not to, prerequisites, limits and return shape, described inputs, an output schema, capped results with pagination, fixable errors, idempotent writes with honest hints, no secrets as arguments, stable ordering and versioned changes, and an evaluation in at least two hosts. There's also a small script to estimate your tool list's token cost. It's a rough rule of thumb, so use your provider's token counter for precise numbers.

5:12 Pitfalls and metrics

Watch for the classics: one tool per API endpoint, generic names that collide, raw vendor payloads, and silent changes after release. Measure by running the same evaluation in at least two hosts, say Claude and an IDE agent, and track correct tool rate, calls per task, tokens per task and error rate as you edit descriptions.

5:36 Breaking changes

How do you handle breaking changes to a tool? Treat tools like a public API. Add new tools or optional parameters rather than changing the meaning of existing ones. If you must break something, publish a new tool name, keep the old one working for a transition period with a description that points to the new one, announce it in your changelog, and remove it only after checking usage. Hosts and agents that depend on you will thank you.

6:10 Deeper: CRM redesign results (illustrative)

Let's deepen the agency CRM redesign, with illustrative numbers from their forty question evaluation. Version one: thirty eight tools, about seven calls per question, and wrong tool selections in roughly one question in four. Version two: nine tools, about three calls per question, and wrong selections rare. The tool list shrank from several thousand tokens to well under half that, which also reduced cost on every call in every host. Account managers noticed the difference as speed: answers arrived noticeably faster. The team kept the evaluation running nightly, and when someone later shortened the contact brief description, accuracy dipped, and they restored it the next morning.

6:56 Watch me do it: checklist on crm_update_deal_stage

Watch me do it. Let's run the design checklist on one real tool, crm update deal stage. Name: specific and prefixed, check. Description: I add, use after crm find deals, only for moving an existing deal between stages, not for creating deals; returns the updated stage. Inputs: deal id described as coming from crm find deals, stage as an enum of the six stages, and an idempotency key. Output schema: deal id, old stage, new stage. Results are tiny, so no pagination needed. Errors: unknown deal says to search first; invalid transition says which stages are allowed next. Annotations: not read only, destructive true, idempotent true. No secrets in arguments. Then I run the token estimate script: nine tools, about eighteen hundred tokens by the rough rule, then I confirm with the provider's token counter. Finally, ten realistic requests in two hosts. Checklist done.

7:59 Try this now

Try this now. Take three tools you plan to ship and run the ten point checklist from the lesson on each. Estimate how many tokens your whole tool list adds to every model call. Then rewrite the weakest tool: consolidate it with a neighbor, sharpen its description, or cut its output down to what the next step needs. Test the before and after versions with five realistic requests in a real host, and keep the numbers.

8:32 Recap

To recap: your server's user is a model working alongside other servers' tools. Design around workflows, name and describe precisely, return compact structured output, make writes idempotent, keep definitions stable, and budget tokens. Your next step: run the checklist on three tools you plan to ship, estimate your tool list's token cost, and rewrite the weakest tool.