Tool Definition Generator
Generate clean function/tool schemas for an LLM agent from existing code or a spec — accurate JSON Schema, model-facing descriptions, honest required fields, and enums that make invalid calls impossible. Use when wiring functions into an agent's tool-calling loop.
Most bad tool calls come from bad tool definitions, not a weak model. This skill turns a function or API spec into a clean tool/function schema written for the model: precise types, honest required fields, enums that constrain choices, and descriptions that say when and how to call it — so invalid calls become structurally impossible.
Install to ~/.claude/skills/tool-definition-generator/SKILL.md
npx agentscamp add skills/tool-definition-generatorWhen an agent calls the wrong tool or passes garbage arguments, the instinct is to blame the model. Far more often, the tool definition is the problem: a vague description, an enum left as a free-string, a required field marked optional. This skill generates tool/function schemas that are written for the model, so correct calls are easy and invalid ones are impossible.
When to use this skill
- Wiring existing functions or API endpoints into an agent's tool-calling loop.
- An agent picks the wrong tool, omits required arguments, or passes malformed values.
- Standardizing tool schemas across an agent codebase.
Instructions
- Read the source of truth. Derive the schema from the actual function signature, types, and docstring (or an OpenAPI spec) — never hand-wave argument names. Inspect call sites to learn real usage.
- Name and describe for the model, not the compiler. The tool name and description are prompt surface: state plainly what it does and when to use it (and when not to). Ambiguous descriptions cause more bad calls than a weak system prompt.
- Type every argument precisely. Use JSON Schema types, mark fields
requiredhonestly (don't mark everything optional to be safe — that invites omissions), and add per-argument descriptions with units and formats ("ISO 8601 date", "USD cents"). - Constrain with enums and bounds. Replace free-strings with
enumwhere the set is known, add min/max and patterns where they apply. A constrained schema makes an invalid call structurally impossible rather than merely discouraged. - Keep the surface tight. Fewer, well-scoped tools beat many overlapping ones. If two tools are easily confused, disambiguate their descriptions or merge them.
- Emit in the target format. Produce the schema in the shape the framework expects (OpenAI/Anthropic tool format, or the agent SDK's decorator), and verify it validates.
TIP
The description is doing prompt engineering. "Refund a charge. Use only after confirming the charge exists and the amount; do not use for subscription cancellations." prevents more misfires than any amount of system-prompt nagging.
NOTE
This generates the interface the model calls. The runtime still needs error handling and (for consequential actions) a human-in-the-loop-gate — a good schema reduces bad calls but doesn't replace guardrails.
Output
Validated tool/function schemas in the target format: precise types, honest required fields, model-facing descriptions, and enums/bounds that constrain inputs — ready to drop into the agent's tool list.
Filed under
Related
- Agent Tool Integration EngineerUse this agent to wire tools and function-calling into an agent loop reliably — clean tool schemas, errors fed back as observations, retries with limits, idempotency, and parallel calls. Examples — "connect our APIs as agent tools", "our agent calls tools wrong / ignores tool errors", "add function-calling with proper error recovery to our agent".
- Production Tool & Function Calling: Feed Errors Back as ObservationsHow agents use tools — the call/observe/retry loop, why errors must return to the model, and the schemas, idempotency, and limits that keep it reliable.
- Which Agent Framework in 2026? LangGraph vs CrewAI vs AutoGen vs OpenAI Agents SDK vs Claude Agent SDKA decision guide to the major AI agent frameworks — control vs. abstraction, multi-agent models, state and durability, and which fits your project.
- OpenAPI Doc WriterProduce and maintain OpenAPI documentation for an HTTP API. Use when documenting endpoints, request/response schemas, or generating API reference docs.
- Function Calling (Tool Calling)Function calling lets an LLM request structured invocations of your code: describe tools with schemas, the model emits typed calls, your app executes them.
- LLM Output Schema GeneratorTurn an example of the data you want from an LLM into a precise, validated output schema (Pydantic / Zod / JSON Schema) and wire it into structured-output calls. Use when adding typed LLM output, replacing brittle JSON parsing, or designing an extraction shape.