Function Calling
Intermediate 12 min read Function Calling

Tool Dispatch

From tool_call to side effect

Dispatch resolves a tool_call to a real handler: a registry, schema validation, allow/deny gates, and an execution envelope that returns results. It is where intent becomes side effects.

dispatchregistryhandlerallowlistexecutionside effects
Prerequisites: Tool Schemas
Before we start

What you will learn

  • Build a tool registry and dispatcher
  • Validate args before execution
  • Gate writes behind allow/deny rules
Introduction

What is this?

Dispatch is the runtime layer between a model's tool_call and your real functions: a registry maps tool names to handlers, validation checks args against schemas, policy gates decide allow/deny (write tools, PII access), and an execution envelope returns results — or safe errors — back to the model.

Motivation

Why do you need it?

  • Centralizing dispatch means new tools are one registration, not scattered ifs.
  • Validation+gates centralize safety at the single chokepoint.
  • Structured envelope results keep the model loop coherent.
  • Logging every call for audit/eval lives in one place.
Think about it

Mental model

Imagine

A switchboard operator

Think of

Tool dispatcher

Every call to the switchboard hits one person (dispatcher) who routes it correctly or denies it under policy — no caller dials functions directly. Wires (handlers), extensions (tools) and permissions all live on the board, checked at the plug.

Mechanics

How it works

  • Register handlers keyed by canonical tool name.
  • On tool_call: look up, validate args via schema.
  • Evaluate policy: allowed tool? role/scope check?
  • Execute inside guarded envelope (timeouts, error catching).
  • Encode result/error into a tool role message, continue loop.

Dispatch path.

tool_call
Registry
Validate
Gate
Execute
Real world

In production

  • Backends centralize a feature's tools in one dispatcher module.
  • Write/delete tools sit behind role checks at dispatch time.
  • Every tool_call is logged with args, decision and result for evals.
Guidelines

Best practices

  • Dispatch by exact name; no dynamic eval of arbitrary code.
  • Validate before policy, policy before execution.
  • Enforce timeouts per tool; kill runaway handlers.
  • Return typed envelopes (ok | error) — the model understands both.
Watch out

Common mistakes

  • Handlers reachable by string without registry checks.
  • Running a write tool on a read-only session.
  • Swallowing handler exceptions as 'empty result'.
Root cause analysis

Common issues

Error
Dispatch calls a nonexistent tool
Root cause

Registry drift vs tool list sent to model

Fix

Generate the model tool list from the registry — one source.

Error
Writes bypassed the gate
Root cause

Gate placed after execution or missing

Fix

Move allow/deny BEFORE execution; test negative cases.

When things break

Debugging tips

  • Right name, wrong handler → registry misregistration; audit names.
  • Denied calls confusing the model → return a denial reason in the envelope.
  • Timeouts spiking → tool too slow; add expect-timeout and degrade.
Interviews

Interview checkpoint

Practice

Hands-on lab

Build a Minimal Tool Dispatcher
35 min · intermediate
In progress
Objectives
  • Implement a name→handler registry
  • Validate args before dispatch
  • Gate write tools behind a role flag

Build a Minimal Tool Dispatcher

35 min · intermediate

0/4 steps
0%
sandbox · Linux sandbox
$
Try these commands
Test yourself

Quick quiz

0/2
1

Order of dispatch safety checks:

2

Tool name strings should never execute arbitrary code.

Go deeper

Official documentation

Function calling patterns (OpenAI)
docs