Tool Use and Function Calling

Tool use is what transforms a language model from a text generator into an agent that can act on the world. By describing a set of functions to the model, you let it decide at runtime which function to call and with what arguments — then execute that call and feed the result back into the conversation.

Defining a tool

Tools are described with a JSON schema that specifies the function name, a plain-English description of what it does, and the parameters it accepts. The description is critical: the model uses it to decide when and whether to call the tool, so a clear, accurate description improves selection accuracy dramatically.

search_tool = {
    "type": "function",
    "function": {
        "name": "web_search",
        "description": "Search the web for current information. Use when the user asks about recent events or facts you may not know.",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "The search query to run",
                },
            },
            "required": ["query"],
        },
    },
}

Dispatching tool calls

When the model emits a tool call, your code is responsible for executing it. A dispatcher maps function names to actual implementations and returns the result as a string. Keep tool implementations thin and deterministic — they should do one thing and be easy to test independently of the agent loop.

import json

def dispatch_tool(name: str, arguments: str) -> str:
    args = json.loads(arguments)
    if name == "web_search":
        return web_search(args["query"])
    if name == "read_file":
        return read_file(args["path"])
    if name == "write_file":
        return write_file(args["path"], args["content"])
    return f"Unknown tool: {name}"

Tool design principles

• One responsibility per tool — the model selects better when each tool does exactly one thing
• Return structured data as a string (JSON or plain text) the model can reason about
• Include error information in the return value rather than raising exceptions into the loop
• Keep side effects explicit — tools that mutate state should say so in their description
• Validate arguments before execution; models occasionally emit out-of-range or wrong-type values