Design MCP tools and errors so the model's next call is the right one
by PaperChaseWebb
Two MCP server builders shared numbers and rules from real use. A Photoshop server with 83 tools kept model-caused bad calls to about 1 in 290 by making every tool distinct, folding variants into parameters, returning errors that list allowed values, and giving the model a short capability map. A design editor server added batch writes with one undo step and idempotency keys that report stale after an undo.
- Price
- Free
- Difficulty
- Advanced
- Setup
- 1 hr
- Format
- .md file
design-mcp-tools-and-errors-so-the-model-s-next-call-is-the-right-one.md · 3 KB · direct download, no signup
What you end up with
Both builders measured before redesigning.
What you get
- A plain-language summary of the workflow
- A fill-in prompt template
- What to watch out for
- A link to the original source
Who it is for
Builders who already use AI agents and want a proven workflow they can copy into their own project.
Works with
Solid chips: the agent is named in this listing's own tools list. Dashed chip: Plain Markdown, so it also pastes into other agents such as Grok Bot, Hermes, OpenClaw or Muse. We list those as compatible by format only, not as tested.
Tools needed
Cost to run: Free with the agent plan you already use.
Time to result: One working session
How it works
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.
Expected: Done before you move to the next step.
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.
Expected: Done before you move to the next step.
Fold variants into parameters instead of adding near-duplicate tools
Fold variants into parameters instead of adding near-duplicate tools.
Expected: Done before you move to the next step.
Return errors with the allowed values and a corrected example
Return errors with the allowed values and a corrected example.
Expected: Done before you move to the next step.
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.
Expected: Done before you move to the next step.
Sample prompt from the pack
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.
Adapted by PaperChaseWebb. Not the original author's prompt.
Free preview of the file
# 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.
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.
- Figures are as reported by the original author and were not re-measured by us.
Questions
Where does this come from?
A public post credited to u/fcf41 (Editmamei) and u/jangtrinh (DESIGN:OS Studio) on r/mcp. Source: https://www.reddit.com/r/mcp/comments/1xjbly4/not_every_mcp_server_fits_in_25_tools_heres_how/
Is it free?
Yes. Feed entries are free to read and download.
Details
Version 1.0 · Updated Oct 30, 2026 · Markdown version of this page
License: Personal and commercial use. Credit the original source when you share the workflow. Download terms
Related
AGENTS.md, CLAUDE.md and Cursor rules starter files
Six fill-in instruction files for coding agents (base, Next.js plus Supabase, FastAPI, browser game, CLAUDE.md pointer, scoped Cursor rules), an Approvals section that makes the agent stop and wait for your yes, a table of what Grok Bot, Claude Code, Codex, Hermes and Cursor each read, a read-only checker for your rule files and 9 prompts to write, trim and test your own.
Ask-first rules for AI agents: hard nos, approval cards and a test set
Paste-in rules that make an agent ask before it sends, spends, posts or deletes, define what a real yes is, and stop retries after a no, plus 12 test scenarios to check it.