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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️2downloads

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.
nametool-calling
descriptionDefine 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

  1. Does the model need access to external data or actions?
    • Yes: define tools and a call loop.
  2. Are calls independent and can be executed in parallel?
    • Yes: allow parallel calls and aggregate results.
  3. Do arguments frequently fail validation?
    • Yes: tighten schemas and add a validation gate.

Workflows

1. Tool Schema Definition

  1. Choose a single, concrete action per tool (fetch, mutate, or transform).
  2. Write a JSON schema with name, description, and parameters.
  3. Use type: object, properties, and required for arguments.
  4. Add enums or patterns where arguments are restricted.
  5. Register the tool list in the model request.

2. Tool Call Execution Loop

  1. Send the prompt with tool definitions.
  2. If a tool call is returned, validate the arguments against the schema.
  3. Execute the tool and capture the result.
  4. Send the tool result back to the model for a final response.

3. Validation Gate for Arguments

  1. Validate required keys and type compatibility.
  2. Reject unknown keys or invalid enum values.
  3. 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+.

References