Foundations
MDX
Tools and Function Calling for AI Agents
How agents move beyond text by invoking APIs, databases, browsers, and application functions.
Editorial review: clarity, operational relevance, safety boundaries, and source quality.
Tools turn intent into action
A tool is a capability the model can request through a defined interface. Examples include searching a knowledge base, reading a calendar, running a calculation, or drafting a change for approval.
A good tool expresses one domain action, not a low-level API accident. `find_customer_orders` is easier to use safely than a generic HTTP requester. Its description should state prerequisites, side effects, and when another tool is preferable. A smaller, distinct tool set generally produces better choices than dozens of overlapping functions.
Schemas create a contract
Function calling constrains a request to a tool name and typed arguments. Clear names, narrow parameters, and useful validation errors make correct tool selection much more likely.
Schemas reduce syntactic errors but do not establish truth or permission. Prefer stable identifiers, enums, bounded strings, and explicit optional fields. Return machine-readable error codes alongside concise recovery guidance. Values such as account ownership, inventory, and approval status must be checked against live systems after parsing.
Execution stays outside the model
The host application decides whether a call is authorized and performs the actual operation. It should treat model-generated arguments as untrusted input and return concise, structured results.
Tool results should contain what the next decision needs: outcome, relevant data, provenance, and retryability. Avoid dumping entire database rows or web pages into context. For writes, support idempotency keys and return the resulting record so the agent can verify the effect rather than assuming success from a 200 response.
Practical example
Designing a refund tool
Instead of `update_order(payload)`, expose `propose_refund(order_id, reason, amount)` and `execute_approved_refund(proposal_id, approval_token)`. The first validates policy and returns the expected balance change without moving money. The second accepts only a short-lived approval tied to that proposal and an idempotency key. The model can investigate and prepare; the runtime controls the consequential boundary.
Field checklist
Apply it in practice
- Give each tool one unmistakable purpose.
- Use narrow types and stable identifiers.
- Return structured errors with recovery paths.
- Make writes idempotent and expose their resulting state.
Decision framework
Questions to answer before you build
A tool is a security and reliability boundary. Its interface should express one domain action, validate every request, and return enough structured evidence for the next decision.
Is the purpose unmistakable?
Prefer domain verbs such as `find_customer_orders` over generic database or HTTP access. State prerequisites, side effects, and non-use cases.
Are the arguments safely bounded?
Use stable identifiers, enums, size limits, server-side defaults, and cross-field validation. Treat every model-produced value as untrusted input.
What happens after uncertainty?
Classify failures as invalid, denied, temporary, or indeterminate. Reconcile an uncertain write before allowing a retry.
Common failure signals
Watch for these warning signs
- Giving the model low-level API access that bypasses domain invariants.
- Returning vague errors that cause blind retries or invented corrections.
- Reporting write success without reading back the resulting state.
Selected primary references
Continue with the source material
These sources inform the wider editorial perspective for this topic. They are not presented as line-by-line citations for every statement.