agent-tools
/agent-tools
Designs and reviews the tools an LLM agent calls: tool/function definitions, JSON schemas, MCP servers, naming, consolidation, descriptions, error messages, response size, tool search, write-tool confirmation. Use when writing tool definitions, building or wrapping an MCP server, turning an API into tools, or when the agent picks the wrong tool, passes bad arguments, loops on errors or floods context with tool output. Not for architecture (agent-design), prompt wording (agent-prompting), memory (agent-context) or retrieval (agent-rag); write-tool permissions pair with agent-guardrails.
- Author
- sarthakrastogi ↗
- Repository
- agent-engineer ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 4
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Designs and reviews the tools an LLM agent calls: tool/function definitions, JSON schemas, MCP servers, naming, consolidation, descriptions, error messages, response size, tool search, write-tool confirmation. Use when writing tool definitions, building or wrapping an MCP server, turning an API into tools, or when the agent picks the wrong tool, passes bad arguments, loops on errors or floods context with tool output. Not for architecture (agent-design), prompt wording (agent-prompting), memory (agent-context) or retrieval (agent-rag); write-tool permissions pair with agent-guardrails.
Original author description
Designs and reviews the tools an LLM agent calls: tool/function definitions, JSON schemas, MCP servers, naming, consolidation, descriptions, error messages, response size, tool search, write-tool confirmation. Use when writing tool definitions, building or wrapping an MCP server, turning an API into tools, or when the agent picks the wrong tool, passes bad arguments, loops on errors or floods context with tool output. Not for architecture (agent-design), prompt wording (agent-prompting), memory (agent-context) or retrieval (agent-rag); write-tool permissions pair with agent-guardrails.
How it works
- Core rules
- Workflow
- Decision rules
- Anti-patterns
- Outputs
- References
SKILL.md preview
---
name: agent-tools
description: >-
Designs and reviews the tools an LLM agent calls: tool/function definitions, JSON schemas,
MCP servers, naming, consolidation, descriptions, error messages, response size, tool
search, write-tool confirmation. Use when writing tool definitions, building or wrapping
an MCP server, turning an API into tools, or when the agent picks the wrong tool, passes
bad arguments, loops on errors or floods context with tool output. Not for architecture
(agent-design), prompt wording (agent-prompting), memory (agent-context) or retrieval
(agent-rag); write-tool permissions pair with agent-guardrails.
license: MIT
metadata:
version: 0.4.0
---
# Agent tools
Design tools for a model that reads every word of the definition and nothing else.
## Core rules
1. **Tools for tasks, not endpoints.** One `schedule_event` beats `list_users` +
`list_events` + `create_event`.
2. **No overlap.** If a human engineer can't say which tool applies, the model can't either.
Agents handle 15+ distinct tools and fail with < 10 overlapping ones.
3. **The description matters most.** 3–4+ sentences: what, when, when not, parameters,
returns, caveats.
4. **Make invalid calls unrepresentable.** Enums, required fields, unambiguous names
(`user_id`), absolute paths. Never ask the model for values your code knows.
5. **Bounded, high-signal results.** Names over UUIDs, pagination and truncation with
guidance, concise default with a detailed option.
6. **Errors are instructions:** what went wrong plus a correct call. No tracebacks, no empty
success on failure.
7. **Separate reads from writes.** Writes are idempotent, narrow and gated by risk;
authorisation is enforced in code, never by the model.
8. **10+ tools or > ~10K tokens of definitions → tool search**; ≤ ~20 loaded at once.
9. **Test tools with the agent** on realistic tasks; remove any tool whose removal doesn't
hurt the eval.
## Workflow
1. Read the Tools section of `agent-engineering/design.md` and the tool code. List the tasks
the agent must accomplish, not the APIs available.
2. Map tasks to a minimal set with the decision rules; note each merge or split.
3. Write each definition against `references/tool-definition-checklist.md`.
4. Shape responses and errors with `references/tool-responses-and-errors.md`.
5. Rate each tool's risk tier; add idempotency keys and confirmation per tier; check
`agent-guardrails` if the agent also reads untrusted content.
6. Decide delivery (native tools, MCP server per `references/mcp-servers.md`, a CLI, or code
execution) and loading (all up front vs tool search).
7. Test with the agent (checklist §7): 30+ tasks plus a held-out set. Read the transcripts
where it chose wrong; have the agent rewrite the descriptions; re-run.
8. Record the tool list (name, purpose, read/write, risk, loading) in `design.md`. Log every
definition change in `experiment-log.md`; descriptions are behaviour.
9. Next: `agent-prompting` for cross-tool policy, `agent-evals` for tool-selection and
argument evals, `agent-guardrails` for write tools.
## Decision rules
| If… | Then |
|---|---|
| Two tools are always called in sequence | Merge them |
| Tools differ only by operation on one resource | One tool with an `action` enum, unless parameters diverge a lot |
| A tool's modes barely share parameters | Split it |
| The agent confuses two tools | "Use X instead when…" in both, rename; still confused → merge or remove one |
| A tool returns lists | Filters + pagination + total count; small default page |
| Output can exceed a few thousand tokens | Truncate with narrowing guidance; offer `concise` / `detailed` |
| The agent must join or aggregate many results | Do it in code and return the summary |
| Nested or format-sensitive input | 1–3 input examples in the definition |
| A tool has side effects | Apply its risk tier's controls (`agent-guardrails` → `references/approvals-and-permissions.md`) |
| Several agents or harnesses need the same tools | MCP server; one app → native tools |
| A good CLI exists and the agent has a sandboxed shell | Consider the CLI over a wrapper |
## Anti-patterns
- One tool per REST endpoint, producing dozens of overlapping tools.
- One-line descriptions, or descriptions in CAPS and MUSTs.
- `data: object` or `query: string` with no format, example or enum.
- Raw API JSON with internal IDs, nulls and unused metadata.
- Stack traces, `{"error": true}`, or `null` instead of a recoverable message.
- Unbounded list or file-read tools.
- Generic `run_sql` / `http_request` / shell tools where a narrow tool would do.
- Letting the model decide whether the user may perform an action.
- Editing the tool list mid-session instead of masking (`agent-context` →
`references/prompt-caching.md`).
- Changing a description without re-running the eval.
## Outputs
Write these to `agent-engineering/` only if the project keeps one (see `agent-engineer` → *Project record (optional)*); otherwise put them in your reply or the PR description.
- Tool definitions and handlers, or an MCP server, in the user's codebase.
- `design.md` → Architecture → Tools; `experiment-log.md` entries with eval deltas.
## References
- `references/tool-definition-checklist.md` — set design, counts, naming, schemas,
descriptions, examples, read vs write, testing with the agent, review checklist. Read when
writing or reviewing any definition.
- `references/tool-responses-and-errors.md` — response shaping, pagination, truncation, bulk
work in code, error classes, retry and escalation. Read when results are large or the
agent loops on errors.
- `references/mcp-servers.md` — when to use MCP, primitives, annotations, transports,
server-side auth, testing. Read when building or connecting MCP servers.
Files in this package (4)
- SKILL.md 6 KB
- references/mcp-servers.md 3 KB
- references/tool-definition-checklist.md 7 KB
- references/tool-responses-and-errors.md 5 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · sarthakrastogi/agent-engineer | 100 | MIT |
| sparq-org/sparq | 87 | MIT |
Database snapshot: 13.11.2026 · package version 681c9d6a331a (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100tool-design
Design tool interfaces for LLM agents — descriptions, parameter schemas, error messages, granularity, and composition. Use when creating function calling tools, building MCP servers, designing agent tool interfaces, writing tool descriptions, or debugging why a model calls the… - 100tool-calling-principles
Use this skill when the user says 'tool calling', 'function calling', 'tool schema', 'JSON schema for tools', 'agent picks wrong tool', 'tool error handling', 'structured outputs', 'tool_use / tool_result'. Designs tool interfaces for LLM agents: naming, descriptions, strict… - 100tool-design
Design the tools a model calls — names, parameter shapes, what a result returns, and error text written as an instruction the model can act on. Use when adding or reshaping a tool or function an LLM invokes, when an agent keeps calling the wrong tool or passing malformed… - 100tool-design
This skill should be used for the tool-interface layer of an agent system specifically: writing tool descriptions agents can route on, designing tool schemas and response formats, naming conventions, actionable error recovery messages, MCP server design, tool-set consolidation,… - 100agent-tool-design
This skill should be used for the tool-interface layer of an agent system specifically: writing tool descriptions agents can route on, designing tool schemas and response formats, naming conventions, actionable error recovery messages, MCP server design, tool-set consolidation,… - 100tool-design
This skill should be used when the user asks to "design agent tools", "create tool descriptions", "reduce tool complexity", "implement MCP tools", or mentions tool consolidation, architectural reduction, tool naming conventions, or agent-tool interfaces. NOT for building MCP…