How to Build Tool Use for LLM Agents (Playbook)

Everything an agent does to the world, it does through tools. Tool design therefore determines both how useful the agent is and how much damage a mistake or manipulation can do. This playbook covers building tool use for LLM agents with contracts, permissions, mediated execution, validation, observability, and testing, following FISTA's AI agents practice. Concepts are in what is function calling and what is an ai tool.

What does the tool layer do?

Component	Function
Tool registry	Contracts, schemas, permissions, consequence levels, owners
Mediation layer	Validation, authorization, policy, gating, execution, logging
Execution	Adapters to systems; sandboxing; idempotency; timeouts
Results	Structured outputs and errors returned to the agent
Observability	Invocation logs with arguments, results, latency, outcomes
Testing	Unit, adversarial, and trajectory tests

Step 1: Design tool contracts

For each tool: a descriptive name, a one-paragraph purpose the model can understand, an input schema with types, constraints, and examples, an output schema, documented side effects, a consequence level (read, reversible write, irreversible or external), required permissions, and failure modes. Keep tools single-purpose and non-overlapping; ambiguous tool sets cause wrong choices. Schema design follows what is structured output.

Step 2: Scope permissions

Grant each agent only the tools its specification requires, and within each tool, the scopes it needs, separated by read and write. Where the agent acts for a user, use delegated user-scoped authorization so it cannot exceed the user's rights. Issue short-lived credentials at run time from a secrets manager. Permission design is in ai access control and the AI agent security architecture whitepaper.

Step 3: Build the mediation layer

All tool calls pass through one layer that: validates arguments against the schema; checks agent and user permissions; applies policy limits (value caps, rate limits, allowed targets); classifies consequence and routes gated actions to approval; executes through adapters with timeouts; and logs everything. Policy lives here, in code, not in prompts. Gate design is in how to build a human review queue.

Step 4: Execute safely

Sandbox execution for code, files, and network; apply egress allowlists; make write tools idempotent with keys so retries do not duplicate effects; enforce timeouts; and never expose raw credentials to the model. Adapter design isolates system quirks from tool contracts.

Step 5: Return structured results and errors

Return outputs conforming to the schema, sized for context (summaries with references for large results), and errors that are structured and informative: what failed, whether it is retryable, and what the agent might do. Bound retries and escalate on repeated failure. Result content is untrusted for injection purposes; see prompt injection defense checklist.

Step 6: Present tools to the model well

Provide tool descriptions and examples that make selection unambiguous; group related tools; include guidance on when not to use a tool; and keep the active tool set small per task, loading tools by task type where the platform allows. Prompt discipline is in context engineering explained.

Step 7: Observe

Log every invocation with agent, user, tool, arguments (redacted per policy), result summary, latency, validation and gate outcomes, and errors, linked to the task trajectory. Alert on unusual tool sequences, first-seen targets, and failure spikes. See the AI observability whitepaper.

Step 8: Test at three levels

Unit-test each tool's validation, execution, idempotency, and error paths; run adversarial tests for injection through arguments and through results; and evaluate trajectories in a simulated environment to confirm correct tool selection, valid arguments, gate compliance, and recovery from errors. Harness design is in how to build an agent evaluation harness.

Worked example: a customer operations agent's tool set

A customer operations agent needs to look up orders, update shipping addresses, issue refunds within policy, and create tickets. Four tools are defined with strict schemas: order lookup (read, user-scoped), address update (reversible write, validated against address services, gated when the order has shipped), refund (irreversible, capped by policy, approval required above a threshold), and ticket creation (write, low consequence). The mediation layer validates arguments, checks the authenticated customer matches the order, applies the refund cap, routes gated actions to the review queue, and logs everything. Refunds are idempotent by order and reason. Unit tests cover each tool; adversarial tests attempt to trigger refunds through injected order notes and fail; trajectory evaluation confirms the agent selects the right tool, passes valid arguments, and escalates ambiguous requests. In production, an alert on a first-seen refund pattern leads to a policy refinement rather than a loss.

What does it cost?

The tool layer is engineering effort and modest runtime overhead; it is where agent safety and reliability are bought. See the AI total cost of ownership whitepaper.

What are the common mistakes?

• Exposing raw APIs as tools without contracts or scopes.
• Dozens of overlapping tools the model cannot choose among.
• Policy in prompts instead of the mediation layer.
• Write tools without idempotency.
• Treating tool results as trusted instructions.
• Testing tools only through the agent, never directly.

How do you phase the tool layer?

Start with read tools only, which lets the agent prove its usefulness with no consequence risk, and use them to establish the mediation layer, logging, and testing habits. Add reversible write tools next, behind validation and idempotency, and measure argument correctness in production. Add irreversible or external tools last, each with an approval gate, and expand autonomy only as trajectory evaluation and gate metrics support it.

How do you handle tools that are slow or unreliable?

Set timeouts per tool, return structured errors the agent can reason about, cache idempotent results, offer degraded alternatives where possible, and cap retries. Agents that hang on a slow tool or loop on a failing one consume budget and trust; agents that report a tool problem and continue where they can remain useful.

How FISTA Solutions builds tool use

FISTA Solutions builds tool layers to this playbook for every agent it delivers: contract-defined tools with strict schemas, least-privilege and delegated permissions, a mediation layer enforcing validation, policy, and gates, sandboxed idempotent execution, structured results and errors, full observability, and three-level testing. The AI agents practice delivers the agents, AI enablement the shared tool registry and mediation platform, and forward deployed engineers integrate tools with your systems and security controls. The record behind the work is 150+ projects with 99.9% uptime.

To scope an agent's tool layer, message FISTA on WhatsApp, or read how to build an mcp server for exposing tools through a standard protocol.