Function Calling

Contents

Overview

flowchart LR
  subgraph LLM["LLM Response"]
    TC["tool_use block"]
  end
  subgraph Pipeline["Function Calling Pipeline"]
    Norm["Normalize Format"]
    Val["Validate Schema"]
    Repair["Repair Arguments"]
    Dispatch["Dispatch Execution"]
    Trunc["Truncate Result"]
    Guard["Context Guard"]
  end
  subgraph Result["Back to LLM"]
    TR["tool_result message"]
  end
  TC --> Norm
  Norm --> Val
  Val -->|Valid| Dispatch
  Val -->|Invalid JSON| Repair
  Repair --> Val
  Dispatch --> Trunc
  Trunc --> Guard
  Guard --> TR

The pipeline is linear in the happy path but includes a repair loop: when schema validation fails due to malformed JSON, the argument repair module attempts to fix common issues (truncated strings, missing brackets, trailing commas) before re-validating. If repair also fails, a ToolInputError is returned to the LLM.

Decision Points

How It Works

Tool Call Normalization

Each LLM provider emits tool calls in a slightly different shape. OpenAI uses function_call with a name and arguments string; Anthropic uses tool_use blocks with a structured input object. The normalization layer (attempt.tool-call-normalization.ts) converts all variants into a canonical internal format:

// Internal canonical tool call format after normalization
interface NormalizedToolCall {
  id: string;                    // Unique call ID (provider-generated)
  name: string;                  // Function name (e.g., "read_file")
  arguments: Record<string, unknown>; // Parsed JSON arguments
  raw: unknown;                  // Original provider-specific payload
}

// Normalization handles:
// 1. OpenAI function_call → NormalizedToolCall
// 2. Anthropic tool_use  → NormalizedToolCall
// 3. String arguments    → parsed JSON object
// 4. Missing IDs         → generated UUID fallback
function normalizeToolCall(
  providerBlock: unknown,
  provider: "openai" | "anthropic" | "google"
): NormalizedToolCall {
  // Provider-specific extraction logic...
  const parsed = typeof raw.arguments === "string"
    ? JSON.parse(raw.arguments)
    : raw.arguments;
  return { id: raw.id ?? crypto.randomUUID(), name: raw.name, arguments: parsed, raw };
}

Schema Validation with TypeBox

Every tool registered in the agent runtime declares its parameter schema using TypeBox. After normalization, the pipeline validates the tool call arguments against the declared schema:

// From schema/typebox.ts — tool schema definition
import { Type, Static } from "@sinclair/typebox";
import { Value } from "@sinclair/typebox/value";

const ReadFileSchema = Type.Object({
  path: Type.String({ description: "Absolute path to the file" }),
  encoding: Type.Optional(Type.Union([
    Type.Literal("utf-8"),
    Type.Literal("base64"),
  ])),
  lineRange: Type.Optional(Type.Tuple([Type.Number(), Type.Number()])),
});

type ReadFileArgs = Static<typeof ReadFileSchema>;

// Validation at call time
function validateToolArgs(schema: TSchema, args: unknown): ValidationResult {
  const errors = [...Value.Errors(schema, args)];
  if (errors.length === 0) return { valid: true, value: Value.Cast(schema, args) };
  return { valid: false, errors: errors.map(e => ({
    path: e.path,
    message: e.message,
    expected: e.schema,
  }))};
}

Argument Repair

LLMs sometimes produce malformed JSON in tool call arguments — truncated strings, missing closing brackets, trailing commas after the last property. The repair module (attempt.tool-call-argument-repair.ts) attempts to fix these issues before re-validating:

Tool Dispatch & the AnyAgentTool Type

Once arguments are validated, the pipeline dispatches execution through the AnyAgentTool wrapper defined in tools/common.ts. This type unifies all tool implementations — built-in tools, MCP tools, and skill-based tools — behind a common interface:

// From tools/common.ts
interface AnyAgentTool {
  name: string;
  description: string;
  schema: TSchema;                       // TypeBox schema
  execute(args: unknown, ctx: ToolContext): Promise<ToolResult>;
  metadata: {
    ownerOnly?: boolean;                 // Requires OWNER_ONLY_TOOL_ERROR check
    category: "read" | "write" | "exec" | "session" | "image";
    sandboxRequired?: boolean;
  };
}

// ToolResult wraps the output with metadata
interface ToolResult {
  content: string | object;
  isError?: boolean;
  errorCode?: number;                    // 400 = ToolInputError, 403 = ToolAuthorizationError
  truncated?: boolean;
}

// Error constants
const OWNER_ONLY_TOOL_ERROR = "This tool is restricted to the workspace owner.";

Parameter Validation Helpers

Individual parameters are validated by utility functions like readStringParam(), which provides fine-grained control over string argument handling:

// Parameter validation utility
function readStringParam(
  args: Record<string, unknown>,
  key: string,
  options?: {
    required?: boolean;      // Throw ToolInputError if missing
    trim?: boolean;          // Trim whitespace (default: true)
    label?: string;          // Human-readable label for error messages
    allowEmpty?: boolean;    // Allow empty string (default: false)
  }
): string | undefined {
  const raw = args[key];
  if (raw === undefined || raw === null) {
    if (options?.required) {
      throw new ToolInputError(
        `Missing required parameter: ${options.label ?? key}`
      );
    }
    return undefined;
  }
  let value = String(raw);
  if (options?.trim !== false) value = value.trim();
  if (!value && !options?.allowEmpty) {
    throw new ToolInputError(
      `Parameter "${options.label ?? key}" must not be empty`
    );
  }
  return value;
}

Tool Call Lifecycle

sequenceDiagram
  participant LLM as LLM
  participant Norm as Normalizer
  participant Schema as Schema Validator
  participant Repair as Arg Repair
  participant Dispatch as Dispatcher
  participant Tool as AnyAgentTool
  participant Trunc as Truncator
  participant Guard as Context Guard
  participant Conv as Conversation

  LLM->>Norm: tool_use block
  Norm->>Schema: NormalizedToolCall
  alt Schema valid
    Schema->>Dispatch: validated args
  else Invalid JSON
    Schema->>Repair: validation errors
    Repair->>Schema: repaired arguments
    alt Repair succeeded
      Schema->>Dispatch: validated args
    else Repair failed
      Schema-->>Conv: ToolInputError (400)
    end
  end
  Dispatch->>Tool: execute(args, ctx)
  alt Owner-only check fails
    Tool-->>Conv: ToolAuthorizationError (403)
  else Execution succeeds
    Tool->>Trunc: raw ToolResult
    Trunc->>Guard: truncated result
    Guard->>Conv: tool_result message
  end

The full lifecycle from LLM emission to tool_result insertion typically takes single-digit milliseconds for built-in tools. Network-dependent tools (HTTP requests, file I/O) add their own latency, but the pipeline overhead is negligible.

Annotated Code Walkthrough

Walk through the complete function calling pipeline from raw LLM output to conversation insertion:

// attempt.tool-call-normalization.ts
export function extractToolCalls(
  response: LLMResponse,
  provider: ProviderFamily
): NormalizedToolCall[] {
  const blocks = response.content.filter(b => b.type === "tool_use");
  return blocks.map(block => normalizeToolCall(block, provider));
}

// OpenAI: arguments is a JSON string
// Anthropic: input is already an object
// Google: functionCall.args is an object
function normalizeToolCall(block: unknown, provider: ProviderFamily): NormalizedToolCall {
  switch (provider) {
    case "openai":
      return { id: block.id, name: block.function.name,
               arguments: JSON.parse(block.function.arguments), raw: block };
    case "anthropic":
      return { id: block.id, name: block.name,
               arguments: block.input, raw: block };
    case "google":
      return { id: block.id ?? crypto.randomUUID(), name: block.functionCall.name,
               arguments: block.functionCall.args, raw: block };
  }
}

// Core validation + repair loop
async function processToolCall(
  call: NormalizedToolCall,
  tool: AnyAgentTool,
  ctx: ToolContext
): Promise<ToolResult> {
  // First attempt: validate as-is
  let validation = validateToolArgs(tool.schema, call.arguments);

  if (!validation.valid) {
    // Attempt repair of malformed JSON
    const repaired = repairToolCallArguments(call.arguments, validation.errors);
    if (repaired !== null) {
      validation = validateToolArgs(tool.schema, repaired);
      if (validation.valid) call.arguments = repaired;
    }
  }

  if (!validation.valid) {
    return { content: formatValidationErrors(validation.errors),
             isError: true, errorCode: 400 };
  }
  // Dispatch to tool execution
  return await tool.execute(validation.value, ctx);
}

// tool-result-truncation.ts
function truncateResult(result: ToolResult, maxChars: number): ToolResult {
  const content = typeof result.content === "string"
    ? result.content
    : JSON.stringify(result.content);
  if (content.length <= maxChars) return result;
  return {
    ...result,
    content: content.slice(0, maxChars) + "\n...[truncated]",
    truncated: true,
  };
}

// tool-result-context-guard.ts
function guardContext(
  result: ToolResult,
  remainingTokens: number
): ToolResult {
  const estimatedTokens = Math.ceil(String(result.content).length / 4);
  if (estimatedTokens <= remainingTokens) return result;
  return {
    content: "[Result too large for remaining context — " +
             estimatedTokens + " tokens estimated, " +
             remainingTokens + " available]",
    isError: true,
    truncated: true,
  };
}

Session Transcript Repair

Over long sessions, the conversation transcript can develop structural issues — orphaned tool_result messages without matching tool_use blocks, or untrusted payloads injected into tool results. Two repair functions maintain transcript integrity:

Edge Cases & Error Handling

Configuration

Related Topics

See also:

• Tool Use overview — parent module covering all tool-related subsystems
• MCP Bridge — how external MCP tool servers connect to the runtime
• Sandbox Execution — Docker/SSH backends for isolated tool execution

Directory Map

src/agents/tools/
├── common.ts                       ← AnyAgentTool type, ToolResult, error constants
├── schema/
│   └── typebox.ts                  ← TypeBox schema definitions for all tools
├── attempt.tool-call-normalization.ts ← Provider format normalization
├── attempt.tool-call-argument-repair.ts ← Malformed JSON repair
├── tool-result-truncation.ts       ← Result size limiting
├── tool-result-context-guard.ts    ← Context overflow protection
├── transcript/
│   ├── repairToolUseResultPairing.ts ← Orphaned tool_result repair
│   └── stripToolResultDetails.ts   ← Untrusted payload removal
└── params/
    └── readStringParam.ts          ← String parameter validation utility