Tools & Function Calling

Why Tools

Weights guess. Tools fetch, compute, and change the world. Agents need both.

Model vs Runtime

The model proposes a name and arguments. Your code validates, runs, and logs. That split is the product.

Read vs Write Tools

Getters observe. Writers change the world. Mix them and retries become incidents.

What Is Not a Tool

A paragraph in a prompt is not a function. If the runtime cannot call it, it is fan fiction.

JSON Schema for Tools

A tool is an API. JSON Schema is how you describe arguments the model may fill — and you must still validate.

Required Fields and Extra Keys

Missing keys fail closed. Extra keys are how injection smuggles SQL. Reject both.

Descriptions Are Prompts

The tool description is a docstring the model will obey poorly. Write when to use it, when not to, and which ids it accepts.

Function Calling

The model returns a name plus arguments. You execute. You send the result back. That is the whole protocol.

The Dispatcher

One table maps names to functions. Unknown names fail. Never run model text as code. Never import os because the model asked.

Coerce and Structured Errors

Turn "17" into 17. Reject -1. Return error codes the model can use, not a 4,000-line traceback.

Parallel Tool Calls

Several reads in one turn can run together. Two refunds of the same invoice cannot. Order and isolation matter.

Observations and Truncation

Tool results go back as data, not as new policy. Cap size. Mark truncated. Never dump a 2 MB log into the next prompt.

Designing Tools

Small, typed tools with boring errors beat a god function that takes a natural-language command.

Idempotency

Agents retry. Networks retry. The model retries because it did not read the first observation. Same key, same result.

Timeouts, Retries, and Size Caps

Hung tools must die. Huge outputs must truncate. Retry reads. Do not blindly retry writes.

Code Interpreters

Let the model write Python for math — then run it in a tiny sandbox, not on your laptop as root.

Browser and Computer Use

A page or a desktop is just state. Clicks, types, and screenshots are tools. Success is a predicate, not a vibe.

Model Context Protocol (MCP)

MCP is a standard way to list and call tools on other servers — not a new brain and not a permission system.

MCP Host Policy

The host decides which servers are on, which tools reach the model, and which calls are audited. “It’s MCP” is not a threat model.

Permissions and Least Privilege

Allowlists, argument bounds, and tight credentials: the model proposes, the policy disposes.

Human Approval

Irreversible calls enqueue for a human. Timeout is a deny. Silence is not consent.

Path and Host Allowlists

read_file needs a folder jail. http_get needs a host allowlist. Check before you fetch, not after.

Identity and the Confused Deputy

The bot’s credential is not the user’s authority. Check what Ada may do, not only what the process key can do.

Tool Fixtures and When Tools Fail

Every tool needs a valid call, a missing field, and an extra key in CI. When the catalog is wrong, stop prompting and fix the functions.