Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →majiayu000/tool-design
Build tools that agents can use effectively, including architectural reduction patterns
Passed 22 of 22 test cases with the skill, and 18 of 22 without it.
and 2 more in the full report
4 fixed18 passed either way0 still failing0 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 4 test cases the skill fixed. Same model, same prompt, with and without the skill.
We are integrating Model Context Protocol integrations across three backend microservices, but our agent keeps encountering execution errors like missing tool lookups and silent failures when parameters are bad. Can you provide a comprehensive tool refactoring guide that outlines how to fix tool routing across multi-server setups, redesign error payloads so agents can recover automatically, and supply a Python sample showing a production-ready function contract?
| Checked | Without skill | With skill |
|---|---|---|
| specifies fully qualified MCP tool names using the ServerName:tool_name format with a colon | Missed | Passed |
| recommends actionable error messages that specify recovery steps or corrected input formats | Passed | Passed |
| includes explicit usage triggers and return format specifications in the tool description | Missed | Passed |
The instructions your model reads when the skill loads.
Tools are the primary mechanism through which agents interact with the world. They define the contract between deterministic systems and non-deterministic agents. Unlike traditional software APIs designed for developers, tool APIs must be designed for language models that reason about intent, infer parameter values, and generate calls from natural language requests. Poor tool design creates failure modes that no amount of prompt engineering can fix. Effective tool design follows specific principles that account for how agents perceive and use tools.
Activate this skill when:
Tools are contracts between deterministic systems and non-deterministic agents. The consolidation principle states that if a human engineer cannot definitively say which tool should be used in a given situation, an agent cannot be expected to do better. Effective tool descriptions are prompt engineering that shapes agent behavior.
Key principles include: clear descriptions that answer what, when, and what returns; response formats that balance completeness and token efficiency; error messages that enable recovery; and consistent conventions that reduce cognitive load.
Tools as Contracts Tools are contracts between deterministic systems and non-deterministic agents. When humans call APIs, they understand the contract and make appropriate requests. Agents must infer the contract from descriptions and generate calls that match expected formats.
This fundamental difference requires rethinking API design. The contract must be unambiguous, examples must illustrate expected patterns, and error messages must guide correction. Every ambiguity in tool definitions becomes a potential failure mode.
Tool Description as Prompt Tool descriptions are loaded into agent context and collectively steer behavior. The descriptions are not just documentation—they are prompt engineering that shapes how agents reason about tool use.
Poor descriptions like "Search the database" with cryptic parameter names force agents to guess. Optimized descriptions include usage context, examples, and defaults. The description answers: what the tool does, when to use it, and what it produces.
Namespacing and Organization As tool collections grow, organization becomes critical. Namespacing groups related tools under common prefixes, helping agents select appropriate tools at the right time.
Namespacing creates clear boundaries between functionality. When an agent needs database information, it routes to the database namespace. When it needs web search, it routes to web namespace.
test cases passed, vs 18 / 22 without
Published skills whose descriptions closely match this one, with their headline benchmark lift.
More skills from the same source and nearby in the registry, with their headline benchmark lift.