Tool Use / Function Calling

How to design, implement, and operate tools for LLM agents: interface design, safety boundaries, idempotency, and observability.

A tool is a function that an LLM can call. The LLM decides when to call it, what arguments to pass, and how to interpret the result. You decide what the function does, what it returns, and what happens when it fails. This split of responsibility is the central design challenge: you need to write tools that a language model can use correctly without access to the model's internal state.

Tool interface design is a form of API design, but the consumer is a language model, not a human programmer. The model reads your tool name and description to decide whether to use it; it reads your parameter names and descriptions to decide what to pass. Be explicit about units, formats, and valid ranges. Describe edge cases and error conditions. A well-described tool with a clear docstring fails less often than a well-implemented tool with a vague description.

Idempotency is non-negotiable for any tool that writes data. Agents retry on failure. If a write tool is not idempotent, a failed-then-retried action creates duplicate records, double charges, or corrupted state. Design write tools to be idempotent from the start: use natural keys, check-then-write patterns, or idempotency keys. The same applies to tools that trigger external systems.

Observability on tool calls is where most data engineering work lives in an agent system. Log every tool call: the input arguments, the output, the latency, whether it succeeded. Trace multi-call sequences with a shared trace ID. Build dashboards on tool error rates, latency distributions, and argument distributions. An agent that is behaving unexpectedly almost always has a tool call in the trace that explains why. Without that trace, debugging is guesswork.

Key resources

• Writing tools for agents (Anthropic Engineering)

  The best practical guide to tool design from engineers who run agents at scale. Covers interface design, error handling, safety, and the common pitfalls. Required reading before you write your first tool.

• Anthropic Tool Use Documentation

  The API reference for Anthropic's function calling, with examples for parallel tool use, error handling, and streaming. The function-calling interface has become a de facto standard; understanding it deeply pays off across providers.

• OpenAI Function Calling Guide

  The OpenAI equivalent. Comparing the two implementations reveals the portability boundaries and the assumptions each provider bakes into the protocol.