# Design MCP tools and errors so the model's next call is the right one

PaperChase agent use case (free feed entry), version 1.0. Source: [u/fcf41 (Editmamei) and u/jangtrinh (DESIGN:OS Studio) on r/mcp](https://www.reddit.com/r/mcp/comments/1xjbly4/not_every_mcp_server_fits_in_25_tools_heres_how/), 2026-10-30.

## What they did

The Photoshop server tracked failures since June: overall failures fell from 3.5% to 1.7% of calls, and most remaining failures were the app itself (timeouts, files, app not running), not the model. The design editor server makes undo part of the tool contract: up to 200 operations in one transaction and one undo group, a dry run, and a retry key that returns 'stale' if the human undid the first write, so the agent re-decides instead of assuming success. Every error has the same shape: code, path, what was received, what was expected, valid options, a corrected example and whether a retry is safe.

## Worth knowing

Both builders measured before redesigning. Copy the error shape first; it is the cheapest change and it fixes the next call. These are their own servers and figures.

## Workflow template

```text
Apply this workflow to [your project]:
1. Log every tool call and split failures into model mistakes and system failures.
2. Make each tool description say when to use it and which neighbour to pick instead.
3. Fold variants into parameters instead of adding near-duplicate tools.
4. Return errors with the allowed values and a corrected example.
5. For writes, add a dry run, batch writes into one undo step and use idempotency keys that report stale after an undo.
Stop and ask me before anything irreversible: deploys, payments, sends or deletes.
```

## Steps

1. **Log every tool call and split failures into model mistakes and system .** Log every tool call and split failures into model mistakes and system failures.
2. **Make each tool description say when to use it and which neighbour to p.** Make each tool description say when to use it and which neighbour to pick instead.
3. **Fold variants into parameters instead of adding near-duplicate tools.** Fold variants into parameters instead of adding near-duplicate tools.
4. **Return errors with the allowed values and a corrected example.** Return errors with the allowed values and a corrected example.
5. **For writes, add a dry run, batch writes into one undo step and use ide.** For writes, add a dry run, batch writes into one undo step and use idempotency keys that report stale after an undo.

## Credit

Workflow reported by u/fcf41 (Editmamei) and u/jangtrinh (DESIGN:OS Studio) on r/mcp: https://www.reddit.com/r/mcp/comments/1xjbly4/not_every_mcp_server_fits_in_25_tools_heres_how/
Related: https://www.reddit.com/r/mcp/comments/1xj9mv3/letting_agents_write_to_a_design_file_over_mcp/

Summary and template written by PaperChaseWebb in our own words. Questions: mgmt@paperchasewebb.com