Tool design

Skill ayaqen/Agents-Scripts/skills/tool-design

Design tools and MCP servers agents call correctly on the first try: schemas, descriptions, outputs, errors.From its SKILL.md

Install

npx -y skills add ayaqen/Agents-Scripts --skill tool-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.4 KB, as published. Nobody here has run it

tool-design

Tools are the API between an agent and the world, and the model reads nothing but the name, description, schema, and returned text — never the implementation behind them. A mediocre model wired to well-designed tools outperforms a strong model wired to confusing ones.

When to use

Building or revising an MCP server or agent tool definitions.
An agent repeatedly misuses, ignores, or retry-loops on a tool — that's a design signal, not a model failure.
Wrapping an existing CLI or REST API for agent use.

Workflow

Design around agent tasks, not existing endpoints: one tool per intention, and collapse multi-call sequences the agent always performs in order into a single tool.
Treat the description as the contract: when to use it, when NOT to use it (name the alternative), side effects, and cost. Front-load the words a task description would contain — routing matches on them.
Make schemas hard to misuse: enums over free-form strings, minimal required fields, sensible defaults, unambiguous names kept consistent across the whole toolset (file_path everywhere or nowhere).
Treat outputs as context the agent must carry: return the minimum that answers the intention, and paginate or truncate large results with explicit markers — silent truncation produces confident wrong answers downstream.
Write errors that teach: what was wrong AND what to do next — valid ranges, did-you-mean, required preconditions. The agent's retry is built from your error text.
Gate danger: destructive operations get dry-run modes or explicit confirmation parameters, and read-only vs. mutating is stated in the description.
Eval the toolset like a prompt (pair with eval-design and prompt-triage): run the target model on realistic tasks and count wrong-tool choices, malformed calls, and retry loops. Iterate on descriptions first — they're the cheapest lever.

Pitfalls

Mirroring a REST API 1:1 — it was designed for programmers with docs, not a model with one screen of schema.
Kitchen-sink tools with a dozen optional parameters: the model guesses, badly.
Returning raw payloads that flood the context window.
Errors that just say "invalid input."
Validating the toolset only with the strongest model, then shipping to a cheaper one that needed the guardrails you skipped.