# Tool Design

> Design and iterate on tools (MCP or direct API) that agents actually use well: prototype-then-evaluate loops, agent-assisted tool optimization, consolidated workflow tools, namespacing, high-signal responses, and token-efficient outputs. Use when writing or refactoring tool definitions, building an MCP server, debugging why an agent misuses/ignores tools, or reviewing tool schemas and description…

- **Type:** Skill
- **Install:** `agentstack add skill-archive228-lab-skills-tool-design`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Archive228](https://agentstack.voostack.com/s/archive228)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Archive228](https://github.com/Archive228)
- **Source:** https://github.com/Archive228/lab-skills/tree/main/skills/tool-design

## Install

```sh
agentstack add skill-archive228-lab-skills-tool-design
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Tool Design for Agents

This skill distills Anthropic's engineering guidance on writing tools that non-deterministic agents use effectively. Tools are a contract between deterministic systems and non-deterministic agents — an agent may call your tool, ignore it, misuse it, or hallucinate around it. The methodology: prototype fast, evaluate against realistic multi-step tasks, let the agent itself analyze transcripts and rewrite the tools, and optimize every tool for the agent's scarce context rather than for API completeness.

## When to use

- Writing or refactoring tool definitions for an agent (MCP server, direct API `tools` parameter, SDK tool registry).
- Deciding which endpoints of an existing API to expose to an agent, and how.
- Debugging an agent that calls the wrong tool, makes redundant calls, pages through data wastefully, or ignores a tool entirely.
- Reviewing tool names, parameter names, descriptions, or response payloads.
- Building an evaluation for a tool set.

Do NOT use for: designing deterministic function APIs consumed only by code (normal API-design rules apply), or prompt engineering unrelated to tool specs.

## Rules

### Prototype, then evaluate

1. Stand up a quick local prototype before polishing anything. Give the coding agent documentation for the target libraries/APIs and the MCP SDK; LLM-friendly docs are often published as flat `llms.txt` files (e.g. `https://docs.anthropic.com/llms.txt`). Wrap the tools in a local MCP server or Desktop extension (DXT) for hands-on testing: `claude mcp add   [args...]` for Claude Code, or `Settings > Developer` / `Settings > Extensions` in the Claude Desktop app. Test the tools yourself first — rough edges you feel are rough edges the agent will hit.
2. Build evaluation tasks from real-world workflows, not toy lookups. Strong tasks require realistic data and multiple — potentially dozens of — tool calls (e.g. "Customer ID 9182 reported that they were charged three times for a single purchase attempt. Find all relevant log entries and determine if any other customers were affected."). Weak tasks hand the agent the answer ("Search the payment logs for `purchase_complete` and `customer_id=9182`").
3. Pair every task with a verifiable outcome — exact string comparison or an LLM judge. Do not make verifiers so strict that formatting or punctuation differences fail correct answers. You may note expected tool calls, but avoid overspecifying: multiple valid solution paths usually exist, and overfitting the grader to one strategy hides good behavior.
4. Run evaluations programmatically with a simple agentic loop (a `while`-loop alternating LLM API calls and tool calls), one task prompt per agent. Ask for reasoning/feedback blocks before tool calls and enable interleaved thinking so you can probe why the agent did or didn't call a tool.
5. Collect more than accuracy: total runtime, tool call count, token consumption, and tool error counts. Redundant calls point at pagination or token-limit tuning; frequent errors point at unclear descriptions or missing input examples.
6. Read the raw transcripts, not just scores — and remember "what agents omit in their feedback and responses can often be more important than what they include" (Anthropic). Example fix from the source: Claude's web search tool kept appending "2025" to queries; improving the tool description corrected it.

### Let the agent optimize its own tools

7. Concatenate evaluation transcripts and paste them into Claude Code; ask it to analyze failures and refactor the tools — it can rewrite many tools at once for consistency. Anthropic reports internal Slack and Asana MCP servers measurably beat their human-written baselines this way, with held-out test sets revealing further gains. Most of the source article's advice came from this loop.

### Choose and shape the tools

8. Do not wrap every API endpoint 1:1. More tools do not improve outcomes; too many or overlapping tools distract agents from efficient strategies. Build a small set of thoughtful tools targeting the high-impact workflows your eval tasks exercise, each with a clear, distinct purpose.
9. Consolidate multi-step workflows into single tools that do the discrete API calls under the hood. Source examples: `schedule_event` (finds availability and books) instead of `list_users` + `list_events` + `create_event`; `search_logs` returning only relevant lines with context instead of `read_logs`; `get_customer_context` compiling everything about a customer instead of `get_customer_by_id` + `list_transactions` + `list_notes`.
10. Respect the asymmetry: computer memory is cheap, agent context is not. Prefer targeted retrieval tools (`search_contacts`, `message_contact`) over dumps (`list_contacts`) that force the agent to read everything token-by-token.
11. Namespace tools under common prefixes when many servers/tools coexist — by service (`asana_search`, `jira_search`) or by resource (`asana_projects_search`, `asana_users_search`). Prefix- vs suffix-based namespacing has non-trivial, LLM-dependent effects on tool-use evals — pick the scheme your own evaluations favor.

### Return meaningful, token-efficient context

12. Return only high-signal information. Prefer semantically meaningful fields (`name`, `image_url`, `file_type`) over low-level technical identifiers (`uuid`, `256px_image_url`, `mime_type`). Resolving UUIDs into natural-language names significantly improves retrieval precision and reduces hallucinations.
13. When downstream calls genuinely need technical IDs (e.g. `search_user(name='jane')` feeding `send_message(id=12345)`), expose a `response_format` enum parameter — `DETAILED = "detailed"` / `CONCISE = "concise"` — so the agent chooses. Source measurement on a Slack thread response: detailed 206 tokens (includes `thread_ts`, `channel_id`, `user_id`), concise 72 tokens — roughly one-third the cost.
14. Bound response size: implement pagination, range selection, filtering, and/or truncation with sensible defaults. Claude Code restricts tool responses to 25,000 tokens by default. Effective context will grow, but the need for context-efficient tools will remain.
15. When you truncate, tell the agent what to do next — steer it toward token-efficient strategies such as many small targeted searches instead of one broad search.
16. Make errors actionable: return specific formatting guidance or example inputs, not opaque error codes or raw tracebacks.
17. There is no one-size-fits-all response format (JSON vs XML vs Markdown). LLMs perform better with formats matching their training data — test formats in your evals.

### Prompt-engineer the tool spec

18. Treat tool descriptions as one of the highest-leverage surfaces — they load directly into the agent's context. "Think of how you would describe your tool to a new hire on your team" (Anthropic): make implicit knowledge explicit — specialized query formats, niche terminology, how resources relate.
19. Use unambiguous parameter names: `user_id`, not `user`. Strict data models plus clear descriptions eliminate ambiguity.
20. Measure description changes with your eval. Anthropic reports Claude Sonnet 3.5 reached state-of-the-art on SWE-bench Verified after precise refinements to tool descriptions dramatically cut error rates.

## Checklist

- [ ] Prototype wired into a local MCP server / DXT and tested by hand before any polish
- [ ] Eval tasks drawn from real workflows; each needs multiple tool calls and has a verifiable outcome
- [ ] Verifier tolerant of formatting differences; expected-tool-call specs not overfit to one strategy
- [ ] Eval loop records runtime, tool call count, token consumption, and error counts — not just accuracy
- [ ] Transcripts read manually; agent-omitted information checked, not just agent-stated feedback
- [ ] Transcripts fed to Claude Code with a request to analyze and refactor the tools; re-run on held-out tasks
- [ ] Tool set consolidated: workflow tools (`schedule_event`-style) replace chains of low-level endpoints
- [ ] No dump-style tools where a targeted search tool would do
- [ ] Tools namespaced with a consistent prefix scheme validated by your own evals
- [ ] Responses use natural-language fields; UUIDs resolved to names; `response_format` (detailed/concise) offered where IDs are sometimes needed
- [ ] Pagination/filtering/truncation with sensible defaults; truncation messages tell the agent the next move
- [ ] Errors return corrective guidance and example inputs
- [ ] Every description written new-hire-clear; parameter names unambiguous (`user_id` not `user`)
- [ ] Each description change re-measured against the eval before shipping

## Anti-patterns

- Wrapping every existing API endpoint as a tool without considering agent affordances.
- Shipping many overlapping tools with fuzzy boundaries — the agent picks wrong or dithers.
- `list_*` dump tools that flood context and force token-by-token scanning.
- Returning `uuid`, `mime_type`, `256px_image_url`-style fields when the agent needs names and meanings.
- Opaque error codes and raw tracebacks instead of guidance the agent can act on.
- Eval tasks that are single-call lookups or that embed the answer in the prompt.
- Verifiers that fail correct answers over punctuation, or that hard-require one tool-call sequence.
- Trusting unit-style "it returns data" checks over transcript reading — silent omissions hide there.
- Ambiguous parameter names (`user`) and descriptions that assume tribal knowledge.
- Hand-tuning tools without an eval, or skipping the agent-driven optimization loop entirely.

## Source

- Writing effective tools for agents — with agents — https://www.anthropic.com/engineering/writing-tools-for-agents — 2025-09-11

Distilled from the official document(s) above on 2026-08-12. If this skill and the source disagree, trust the source.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Archive228](https://github.com/Archive228)
- **Source:** [Archive228/lab-skills](https://github.com/Archive228/lab-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-archive228-lab-skills-tool-design
- Seller: https://agentstack.voostack.com/s/archive228
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.