Tool Descriptions
When To Use
The agent picks the wrong tool or misreads what a tool returns. It calls the customer search when it needed the order lookup, or gets back a wall of IDs and guesses. It answers: how should each tool be named, described and shaped so the agent uses it the way a new teammate would?
When Not To Use
This skill writes tools; it does not decide which tools exist or what they may touch. If that is still open, run the Agent Spec first. If the agent picks the right tool but reads the wrong documents, use the Context Engineering Brief.
Inputs
- The tools the Agent Spec allows, with today's names, descriptions, parameters and a sample of what each returns
- Transcripts where the agent chose the wrong tool or misused a result, with personal data masked
If you have none of this, I start from the list of actions the agent must take and mark the output as a first draft.
Approach
The method is Anthropic Engineering's "Writing effective tools for agents": fewer, higher-impact tools rather than one per endpoint, names grouped by a shared prefix, descriptions written the way you would onboard a new teammate, returns that carry meaning rather than cryptic IDs, and errors that say what to do next. Tools are tested with realistic multi-step tasks, not single calls. The failure it prevents: two tools called "search" and "find" that do nearly the same thing, so the agent flips between them and every run looks different.
Workflow
- Ask three questions: which real workflows must the agent complete, which tools confuse it today, and who on engineering implements the changes?
- Consolidate: group operations a person would do together into one tool (look up an order and its status, not three calls). Do not wrap every endpoint.
- Name with a shared prefix by service or resource so similar tools are told apart, and use parameter names that cannot be misread ("customer_email", not "id").
- Write each description like onboarding a teammate: what it does, when to use it, when not to, and the implicit context a newcomer would lack.
- Shape the output: readable fields (names over internal IDs), a concise and a detailed format, and sensible defaults for paging, filtering or truncation so one call cannot flood the context.
- Write error messages that tell the agent the next move ("no order found for that email; ask the user for the order number"), never a bare code.
- Run the overlap check on every pair the agent could confuse: merge, rename or sharpen the boundary. Then write three realistic multi-step test tasks drawn from real workflows. On Claude Code or the Claude Agent SDK, engineering can run them; in any chat, walk them through by hand.
Output Format
# Tool Descriptions
**Agent:** [name] | **Tool set version:** [number] | **Engineering owner:** [role]
## Tools
| Name (prefixed) | Purpose, when to use, when not to | Inputs (name, type, meaning) | Output fields and default format | Error message and next move |
|---|---|---|---|---|
| [prefix_tool] | [description] | [parameters] | [fields] | [message] |
## Overlap check
| Tool pair | Why the agent could confuse them | Fix (merge, rename, sharpen) |
|---|---|---|
| [tool A / tool B] | [reason] | [fix] |
## Test tasks
| Task (real workflow) | Tools expected, in order | Result |
|---|---|---|
| [task] | [tools] | [pass / fail / not yet run] |
## Decision
[Named engineering owner] agrees which changes ship in the next tool set by [date].
Done When
- Every tool has a prefix, a when-not-to-use line and an error message with a next move
- Every confusable pair has a fix
- Three test tasks come from real workflows, with results only from a pasted run
- No tool returns more fields than the task needs
Quality Bar
- One tool per job a person would recognise; a new tool must say why an existing one cannot do it
- Descriptions name the boundary with the nearest tool explicitly
- Tools that return personal data return only the fields the task needs
- Test results are never filled by Claude: [not yet run] until the user pastes the run
- Failed test tasks are grouped by failure type (wrong tool, wrong input, misread output), not counted as one score
Next
Run aipm-error-analysis (Error Analysis) to read real outputs once the agent runs.
About the makers
This pack is made by 90n (90n.ai): AI-native ways of working and tools for Product, Marketing and HR teams, built by ex-McKinsey founders. We map where time and money leak, redesign the work around AI and stay until your people run it themselves, and we run our own company on Claude. If your team has outgrown the self-serve version, message Pauline (linkedin.com/in/paulinebertry).
1---2name: aipm-tool-descriptions3description: Writes Tool Descriptions for an agent with each tool's name, purpose, inputs, outputs and error messages, a namespacing scheme, an overlap check between tools and three realistic test tasks. Use for "run aipm-tool-descriptions", "write tool descriptions", "the agent picks the wrong tool", "tool definitions for our agent", "MCP tool descriptions", "name our agent tools", "the agent misreads what the tool returns", part of the Claude for AI Product Managers Pack by 90n.4metadata:5 source: https://skillmd.com/skills/polar-bear-org/aipm-tool-descriptions6---78# Tool Descriptions910## When To Use11The agent picks the wrong tool or misreads what a tool returns. It calls the customer search when it needed the order lookup, or gets back a wall of IDs and guesses. It answers: how should each tool be named, described and shaped so the agent uses it the way a new teammate would?1213## When Not To Use14This skill writes tools; it does not decide which tools exist or what they may touch. If that is still open, run the Agent Spec first. If the agent picks the right tool but reads the wrong documents, use the Context Engineering Brief.1516## Inputs17- The tools the Agent Spec allows, with today's names, descriptions, parameters and a sample of what each returns18- Transcripts where the agent chose the wrong tool or misused a result, with personal data masked19If you have none of this, I start from the list of actions the agent must take and mark the output as a first draft.2021## Approach22The method is Anthropic Engineering's "Writing effective tools for agents": fewer, higher-impact tools rather than one per endpoint, names grouped by a shared prefix, descriptions written the way you would onboard a new teammate, returns that carry meaning rather than cryptic IDs, and errors that say what to do next. Tools are tested with realistic multi-step tasks, not single calls. The failure it prevents: two tools called "search" and "find" that do nearly the same thing, so the agent flips between them and every run looks different.2324## Workflow251. Ask three questions: which real workflows must the agent complete, which tools confuse it today, and who on engineering implements the changes?262. Consolidate: group operations a person would do together into one tool (look up an order and its status, not three calls). Do not wrap every endpoint.273. Name with a shared prefix by service or resource so similar tools are told apart, and use parameter names that cannot be misread ("customer_email", not "id").284. Write each description like onboarding a teammate: what it does, when to use it, when not to, and the implicit context a newcomer would lack.295. Shape the output: readable fields (names over internal IDs), a concise and a detailed format, and sensible defaults for paging, filtering or truncation so one call cannot flood the context.306. Write error messages that tell the agent the next move ("no order found for that email; ask the user for the order number"), never a bare code.317. Run the overlap check on every pair the agent could confuse: merge, rename or sharpen the boundary. Then write three realistic multi-step test tasks drawn from real workflows. On Claude Code or the Claude Agent SDK, engineering can run them; in any chat, walk them through by hand.3233## Output Format34```markdown35# Tool Descriptions36**Agent:** [name] | **Tool set version:** [number] | **Engineering owner:** [role]37## Tools38| Name (prefixed) | Purpose, when to use, when not to | Inputs (name, type, meaning) | Output fields and default format | Error message and next move |39|---|---|---|---|---|40| [prefix_tool] | [description] | [parameters] | [fields] | [message] |41## Overlap check42| Tool pair | Why the agent could confuse them | Fix (merge, rename, sharpen) |43|---|---|---|44| [tool A / tool B] | [reason] | [fix] |45## Test tasks46| Task (real workflow) | Tools expected, in order | Result |47|---|---|---|48| [task] | [tools] | [pass / fail / not yet run] |49## Decision50[Named engineering owner] agrees which changes ship in the next tool set by [date].51```5253## Done When54- Every tool has a prefix, a when-not-to-use line and an error message with a next move55- Every confusable pair has a fix56- Three test tasks come from real workflows, with results only from a pasted run57- No tool returns more fields than the task needs5859## Quality Bar60- One tool per job a person would recognise; a new tool must say why an existing one cannot do it61- Descriptions name the boundary with the nearest tool explicitly62- Tools that return personal data return only the fields the task needs63- Test results are never filled by Claude: [not yet run] until the user pastes the run64- Failed test tasks are grouped by failure type (wrong tool, wrong input, misread output), not counted as one score6566## Next67Run aipm-error-analysis (Error Analysis) to read real outputs once the agent runs.6869## About the makers7071This pack is made by 90n ([90n.ai](https://90n.ai)): AI-native ways of working and tools for Product, Marketing and HR teams, built by ex-McKinsey founders. We map where time and money leak, redesign the work around AI and stay until your people run it themselves, and we run our own company on Claude. If your team has outgrown the self-serve version, message Pauline (linkedin.com/in/paulinebertry).