Getting it into your agent
One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.
npx skills add latestaiagents/agent-skills --skill mcp-tool-designgit clone --depth 1 https://github.com/latestaiagents/agent-skillsWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/latestaiagents/agent-skills/mcp-tool-design)<a href="https://agentmods.dev/skills/latestaiagents/agent-skills/mcp-tool-design"><img src="https://agentmods.dev/badge/skills/latestaiagents/agent-skills/mcp-tool-design/github.svg" alt="Measured on agentmods" height="20"></a>Or the 80×15 button, for a site that already has a row of RSS and ATOM ones. Only the verdict fits; the numbers stay here.
<a href="https://agentmods.dev/skills/latestaiagents/agent-skills/mcp-tool-design"><img src="https://agentmods.dev/badge/skills/latestaiagents/agent-skills/mcp-tool-design.svg" alt="Reviewed on agentmods" width="80" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00098 | $0.01472 |
| Opus 5 | $0.00049 | $0.00736 |
| Sonnet 5 | $0.00020 | $0.00294 |
| Haiku 4.5 | $0.00010 | $0.00147 |
Grade A, and why
mcp-tool-design scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 9d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Nothing flagged
None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.
How it starts
The opening of the file, as written. The whole thing — 137 lines — stays where its author put it; the contents beside it link to each section on GitHub.
MCP Tool Design
A well-designed tool is invoked correctly by the agent on the first try. A bad one causes loops, wrong-tool selection, or hallucinated arguments.
When to Use
- Adding a new tool to an MCP server
- Debugging "the model never picks this tool" or "the model picks the wrong tool"
- Reviewing a PR that adds tools
- Cleaning up a server with 30+ tools
The Three Levers
Agents pick tools based on name, description, and parameter schema — in that order of signal strength. Every design choice should strengthen at least one.
Naming Rules
| Good | Bad | Why |
|---|---|---|
search_issues |
issueSearcher |
snake_case, verb-led |
get_user_by_email |
user_lookup |
specific over vague |
create_pr_comment |
comment |
namespaced by object |
list_repos |
repos |
action is explicit |
Rule: <verb>_<object>[_<qualifier>]. If two tools could answer the same query, one has the wrong name.
Description Rules
Descriptions are what the model reads most carefully. Budget ~1-3 sentences:
<Verb-led action>. <When to use it / when NOT to use it>. <Any gotchas>.
Example — weak vs strong
Weak:
Creates an issue.
Strong:
Create a GitHub issue in the specified repo. Use this for new bug reports or feature requests. Do NOT use to comment on an existing issue — use
create_issue_commentfor that. Title is required; body supports markdown.
The "when NOT to use" line is the highest-leverage sentence you can write — it routes disambiguation without the agent needing to enumerate all tools.
Parameter Schema Rules
- Describe every field —
.describe()in Zod,Field(description=...)in Pydantic. Undescribed fields get hallucinated values - Use enums for closed sets —
priority: z.enum(["low", "med", "high"])beatspriority: z.string() - Default the optional — if 80% of calls use
limit=50, set the default; don't make the agent guess - Prefer primitives at the top level — nested objects increase hallucination rates
- Avoid freeform "options" bags — split into discrete flags
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 9d ago First seen · 137 lines · 98 tokens per session scan A 37107ce586db
mcp-tool-design is a skill published in the GitHub repository latestaiagents/agent-skills (5 stars, last pushed 4mo ago), licensed MIT. It adds 98 tokens to every session and 1,472 once invoked, about $0.0005 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-09-03.
Other skills, from other repositories
fw-review
Full Freshworks marketplace app review — iparams, frontend, serverless, FDK, security, and structured text report output — in one skill.
ai-design-taste-frontend
A frontend visual-quality reviewer that examines whether an interface looks polished and coherent. It produces visual or creative diagnoses, prompt or storyboard ideas, and publishing checks.
ai-email-sequence-builder
An email-sequence helper for assessing whether a series of emails is likely to prompt action. It creates a summary, findings, recommended actions, and reusable deliverables.
ai-firecrawl
A business-diagnosis assistant for examining questions about what to do next, using supplied material.
ai-gws-sheets
A business-diagnosis assistant for turning spreadsheet-related input into a summary, conclusions, recommended actions, and reusable deliverables.
ai-humanizer-zh
A Chinese writing editor that detects signs of AI-generated prose and rewrites the text to sound more natural.