Tool Calling

Tool Calling vs Tool Execution

This separation is important because your application remains in control of permissions, validation, errors, and side effects.

A Tool Needs a Clear Contract

A good tool definition tells the model what the tool does and exactly which arguments are accepted.

• Name: a short, descriptive identifier.
• Description: when and why the tool should be used.
• Parameters: structured inputs with clear types.
• Required fields: arguments that must be supplied.
• Return shape: predictable output for the model.

Python: Define a Simple Tool

Here is a simple Python tool contract and implementation:

def get_weather(city: str) -> dict:
    # Replace this with a real weather API call.
    return {
        "city": city,
        "temperature_c": 24,
        "condition": "Sunny"
    }

tool = {
    "name": "get_weather",
    "description": "Get the current weather for a city.",
    "parameters": {
        "city": {
            "type": "string",
            "description": "City name"
        }
    },
    "required": ["city"]
}

The Tool-Calling Loop

A typical agent application follows this loop:

If the model does not request a tool, the application can return the model's normal response. If it does, the application executes the approved tool and gives the result back to the model.

Structured Arguments

Tool calls should use structured data rather than asking the model to produce arbitrary text for your application to parse.

Structured arguments make validation, logging, retries, and error handling much more reliable.

Python: Validate Before Execution

Never assume model-generated arguments are safe or complete.

def run_weather_tool(arguments: dict) -> dict:
    city = arguments.get("city")

    if not isinstance(city, str) or not city.strip():
        return {"error": "A valid city is required."}

    city = city.strip()

    if len(city) > 100:
        return {"error": "City name is too long."}

    return get_weather(city)

Handling Tool Errors

Tool Calling with Multiple Tools

An agent may have many tools. The model can select the tool that best matches the user's request, but the application should still enforce an allowlist.

For sensitive actions, require stronger controls such as confirmation, authentication, authorization, or human approval.

Tool Calling + RAG

RAG retrieves knowledge, while tools let an agent perform operations or access live systems. They can work together.

For example, a support agent could retrieve the return policy with RAG and then call an order-status tool to inspect a customer's current order.

Permissions and Safety

• Give each tool the minimum permissions it needs.
• Validate every argument on the application side.
• Never trust a model-generated tool call as authorization.
• Separate read-only tools from tools that change data.
• Require confirmation for high-impact actions.
• Log tool calls without exposing secrets or sensitive values unnecessarily.

Common Mistakes

1. Writing vague tool descriptions.
2. Accepting arbitrary arguments without validation.
3. Letting the model directly control credentials.
4. Returning inconsistent tool-result formats.
5. Giving an agent too many overlapping tools.
6. Allowing irreversible actions without confirmation.

Quick Quiz