tool-calling
Define and run tool-calling patterns for LLMs (schema design, call loops, validation, parallel calls). Use when building function/tool calling workflows or debugging tool selection and arguments; triggers: tool-calling, function-calling, tool schema, tool declaration, parallel function calling.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for defining and executing tool-calling patterns for Large Language Models (LLMs). It enables developers to design robust JSON schemas, implement secure execution loops, and handle parallel function calls with built-in validation gates, ensuring reliable and structured interactions between AI agents and external APIs or data sources.
Use Cases
- Building autonomous AI agents that require real-time data retrieval or action execution through external API integrations.
- Implementing complex multi-step workflows where the model must dynamically select and sequence multiple tools based on user intent.
- Debugging and optimizing tool selection accuracy by refining JSON schemas and implementing validation gates to catch malformed arguments.
- Enhancing system performance by enabling parallel function calling for independent tasks, such as querying multiple databases simultaneously.
- Creating secure agentic workflows by treating model-generated tool calls as suggestions that undergo strict schema validation before execution.
| name | tool-calling |
|---|---|
| description | Define and run tool-calling patterns for LLMs (schema design, call loops, validation, parallel calls). Use when building function/tool calling workflows or debugging tool selection and arguments; triggers: tool-calling, function-calling, tool schema, tool declaration, parallel function calling. |
Tool Calling
Overview
Define tools as structured interfaces the model can call, then implement a loop that executes those calls and returns results. Treat tool calls as suggestions that must be validated before execution.
When to Use
- Use this skill when the frontmatter triggers apply; otherwise start with a simple prompt or deterministic workflow.
Decision Tree
- Does the model need access to external data or actions?
- Yes: define tools and a call loop.
- Are calls independent and can be executed in parallel?
- Yes: allow parallel calls and aggregate results.
- Do arguments frequently fail validation?
- Yes: tighten schemas and add a validation gate.
Workflows
1. Tool Schema Definition
- Choose a single, concrete action per tool (fetch, mutate, or transform).
- Write a JSON schema with
name,description, andparameters. - Use
type: object,properties, andrequiredfor arguments. - Add enums or patterns where arguments are restricted.
- Register the tool list in the model request.
2. Tool Call Execution Loop
- Send the prompt with tool definitions.
- If a tool call is returned, validate the arguments against the schema.
- Execute the tool and capture the result.
- Send the tool result back to the model for a final response.
3. Validation Gate for Arguments
- Validate required keys and type compatibility.
- Reject unknown keys or invalid enum values.
- If validation fails, return a structured error to the model and request a corrected call.
Non-Obvious Insights
- Tool calls are model decisions; treat them as requests and gate with validation.
- Tool schemas are the only interface the model sees, so the schema quality directly shapes behavior.
- Schemas specify how to call functions; ambiguous or incomplete schemas yield ambiguous arguments.
- Parallel calls should only be used when calls do not depend on each other.
Evidence
- "the model determines when to call specific functions and provides the necessary parameters to execute real-world actions." - Google AI
- "schema specifying how to call one or more of the declared functions in order to respond to the user's question." - Google AI
- "A function or tool refers in the abstract to a piece of functionality that we tell the model it has access to." - OpenAI
- "As a model generates a response to a prompt, it may decide that it needs data or functionality provided by a tool to follow the prompt's instructions." - OpenAI
Scripts
scripts/tool-calling_tool.py: CLI for linting tool schemas and validating tool calls.scripts/tool-calling_tool.js: Node.js CLI for the same checks.
Dependencies
- Python 3.11+ or Node 18+.