Function Calling and the Tools an Agent Reaches For
An agent that can only generate text is a very good parrot. The moment it becomes genuinely useful is the moment it can call a function — write to a file, query a database, run a search, or send a message. Tool calling is the hinge on which every real agent swings. Yet most of the pain in building agents lives in exactly this layer: not in making the model call a function, but in designing the functions so the model calls them correctly, safely, and at the right time. This article is about that craft.
What Function Calling Actually Is
Function calling is a structured way for a model to declare, in its output, that it wants to invoke a specific tool with specific arguments. You describe each tool to the model — its name, a description, and a JSON schema for its parameters. When the model decides a tool is needed, it emits a structured call rather than natural language. Your code executes the function, returns the result, and the model incorporates that result into its next step. The model never runs your code; it only requests it. That boundary is your single greatest safety lever.
"The model is a planner with excellent taste but no hands. Functions are the hands. Your job is to make sure it reaches for the right hand, with the right grip, at the right time."
The quality of this entire mechanism rests on your tool descriptions. The model does not read the function body; it reads the docstring. If your description is vague, the model will guess wrong. If your schema is loose, the model will pass malformed arguments. Writing good tool metadata is now a first-class skill, on par with writing good prompts.
Designing Tools a Model Can Use Well
Great agent tools share a handful of properties that make them easy to invoke correctly.
Narrow Tools Over Swiss-Army Tools
A function with a signature that does everything is a function the model can misuse every way. Prefer narrow, single-purpose functions with clear inputs. send_email(to, subject, body) beats do_thing(params). When a narrow tool composes poorly, add a narrow orchestrating tool — not a general one. The model reasons more reliably about small, unambiguous actions.
Schema Clarity Is Interface Design
Every field needs an unambiguous name, type, description, and — critically — whether it is required. Enums and format hints prevent the model from inventing values. If a field accepts only a few options, list them in the schema rather than hoping the model guesses. Include examples. A schematized, well-documented tool is a tool the model uses correctly; a lazily documented one is a source of silent failures.
Make Failures Informative
When a tool fails, return a structured error a model can reason about, not a bare exception message. Instead of "Error", return {"status": "not_found", "message": "No user matches id 412", "suggestion": "List users first"}. The agent can then recover — query again, correct its argument, or ask for help. Good error design converts mistakes into learning.
Safeguards Between the Model and Your Systems
The model's request is a suggestion, not an order. Every tool call must pass through a layer that validates, sanitizes, and authorizes.
- Validate every argument against your own rules, not just the schema. Type checks, length limits, and allowed-values filters catch what the model's confidence misses.
- Never expose destructive powers directly. Wrap deletes and writes behind confirmation, or require an explicit capability flag the model cannot grant itself.
- Rate-limit and observe. Count how many times a tool gets called and what it costs, so a runaway loop becomes visible in a dashboard instead of a surprise invoice.
- Separate read and write. Agents often need broad read access but narrow write access. Model that split explicitly.
Common Failure Modes and Fixes
Even well-designed tool layers drift. Here are the failure modes I see most.
"Every runaway agent loop is a design failure upstream — a tool that was too powerful, a description too vague, or an error too uninformative. Fix the tool, not the loop."
The hallucinated argument happens when the model invents a value because a real one is not in its context. Fix it by making the tool resolve missing values, or by instructing the agent to fetch them first. The tool-dumping deluge occurs when the agent calls read tools in a stream and dumps results into its context until nothing fits. Fix it by designing tools that return summaries, excerpts, or paginated slices instead of full datasets. And the dithering loop — the agent calls the same tool twice with the same arguments and expects a different outcome — is fixed by making the results persistent and visible in shared state so the agent registers that nothing changed.
Observability: The Tool-Calling Telemetry Nobody Buys
You cannot improve a tool layer you cannot see. Instrument every call with a few fields and you will quickly learn where your agent's fragile points live. Track which tools get called most, which ones return errors, how long each call takes, and how many calls the agent wastes before succeeding. That telemetry is the boring engine of quality. A tool that gets called a hundred times and fails silently is not a tool problem — it is a signal that your agent is thrashing, and telemetry is the only way to see it. Log the model's stated reasoning for each call too; it is invaluable for understanding whether a bug is a schema problem or a strategy one.
An Approach That Scales
Start with a small set of genuinely useful tools and expand only on evidence of need. Document each as if a stranger will operate it. Route every call through a validation layer, and instrument counts and latencies from day one. Treat the tool layer as the real product surface — because for the user, that is exactly what it is. The model is the brain, but the functions are the work.
