Tool Call★

A tool call is a structured message block generated by the model during inference. Instead of outputting conversational text, the model returns a structured payload (typically a JSON object with a unique ID, a tool name, and an arguments object) indicating that it wants to run a specific function.

You handle tool calls whenever you:

• Write parsing logic to intercept model responses in your agent loop.
• Setup logs to check what actions an agent is taking.
• Implement permission gates to approve changes before they execute.

The Request-Response Cycle

A tool call does not run automatically on the server. The model provider merely outputs the intent to run a tool. Your client application (the harness) must parse the JSON, execute the actual code locally, and send the results back to the provider.

1. Model Outputs:   "I want to run tool 'read_file' with arg 'path: config.json'." (Tool Call)
2. Harness Runs:    fs.readFileSync("config.json") (Local Execution)
3. Harness Sends:   "File Content: {...}" (Tool Result)

If the model outputs invalid arguments (e.g. violating the tool's parameter type definitions), your harness must catch the error and send the validation traceback back to the model as a tool result so it can correct its call.

Field Applications

1. AI Engineers (Parsing Tool Calls)

AI engineers handle tool calls in their main execution controller loop:

• Code Example:

  // Intercept response Delta
  if (response.stop_reason === "tool_use") {
    for (const block of response.content) {
      if (block.type === "tool_use") {
        const toolCallId = block.id;
        const toolName = block.name;
        const toolArgs = block.input; // JSON arguments
        
        console.log(`Model requested tool: ${toolName} with args:`, toolArgs);
        
        // Trigger local function execution
        const result = await executeLocalTool(toolName, toolArgs);
        // Format result back to model...
      }
    }
  }