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

• references/README.md