Design the Tool Surface for an Agent or MCP Server

    You are an engineer who has built agent tool surfaces and learned that the hard problem is not writing one tool well, it is deciding which tools should exist. Selection errors compound through everything downstream, so the shape of the surface matters more than the polish of any single description.

What the agent needs to accomplish: {{agent_purpose}}
The underlying API, database, or system it wraps: {{underlying_system}}
Tools I have or am planning: {{current_tools}}
Who calls this surface — one agent, several, or third-party clients: {{consumers}}
Typical task the agent performs end to end: {{example_task}}

Work through this.

1. **Design around tasks, not endpoints.** The most common mistake is exposing one tool per API endpoint and making the model assemble a workflow out of six calls. Walk my example task and say which sequences should collapse into a single tool that does the whole job. Fewer, higher-level tools produce fewer failure points and fewer round trips.

2. **Get the granularity right in both directions.** Flag tools that are too fine — the model has to chain them and can get the order wrong — and tools that are too coarse, where a single call takes so many parameters that the model fills them in wrongly. For each, say what to merge or split.

3. **Prune.** Every tool costs tokens in the window on every single turn and adds a wrong option to every selection decision. Which tools can be removed, merged, or hidden behind a mode? Give me a target count and the reasoning. If the surface must stay large, say how to scope it per task instead.

4. **Make the names and boundaries unambiguous.** For any two tools a model might confuse, either rename them so the distinction is obvious from the name alone, or merge them. State the confusable pairs explicitly — this is where selection accuracy is won or lost.

5. **Design the return values.** What comes back, in what shape, how large it is allowed to get, and what gets truncated or summarized before it enters context. Tool output is usually the biggest uncurated thing in an agent's window. Include what a good error return looks like: enough for the model to correct itself, not a stack trace.

6. **Handle the destructive ones.** Which tools change state, cost money, or contact a third party, and how that is signalled in the surface itself rather than left to the agent's judgment.

Return the recommended tool list with one-line purposes, the changes from what I have, and the two decisions you were least certain about.