Tool design for AI agents: how to give models the right hands

A language model can think, explain, summarize, classify, draft, and reason. But on its own, it cannot check your inventory system, inspect a customer order, update a CRM record, send an email, or execute code. It cannot change the external world.

To do those things, an AI agent needs tools: the controlled interfaces through which a model interacts with data, software, workflows, and people. A simple way to say it: tools are the hands of an AI agent. The model may decide what should happen; the tools determine what the agent can actually do. That is why tool design is one of the most important disciplines in agentic AI. A powerful model with poorly designed tools can become unreliable, expensive, or dangerous. A modest model with well-designed tools can become surprisingly useful, predictable, and safe.

Tool design determines what the agent can access, what it can change, what it can only inspect, what requires approval, what information comes back, how errors are handled, whether actions can be repeated safely, and whether humans can understand what happened. The difference is not just technical. It is operational.

A tool is not just an API. A tool is an action interface designed for a model, governed by a system, and accountable to a workflow.

Without tools, a model can only produce text: a summary, an explanation, a plan, a recommendation. That can be valuable, but it remains trapped inside language. With tools, the interaction becomes a loop — the model decides what is needed, a tool retrieves or performs something, the observation returns, and the model decides the next step.

User:   Can this customer receive a refund?
Model:  I need the order, delivery status,
        and refund policy.
Tool:   get_order(order_id)
Obs:    Delivered yesterday. Total €47.80.
Tool:   retrieve_refund_policy(category)
Obs:    Damaged goods reported within seven
        days are eligible.
Model:  The customer is eligible for a
        €47.80 refund.

The model’s answer is now grounded in external information. The tool made the difference. This is the gap between an AI assistant that talks about work and an AI agent that participates in work.

The toolset is the agent’s action space

An agent can only act through the actions available to it. A support agent with only a knowledge-base search tool can answer questions but cannot resolve cases. Add a refund calculator and it can assess eligibility; add an approval request tool and it can prepare an action; add an execution tool and it can actually issue the refund. Each added tool changes the agent’s power. Tool design is not an implementation detail. It is agency design.

A tool is not just an API

Enterprise systems already have APIs, but giving a model raw API access is usually a mistake. An API is designed for software engineers and deterministic programs — a wall of endpoints like POST /v2/transactions/reversal where a human engineer knows the required fields, side effects, and permissions. An agent tool is designed for a probabilistic model operating through language: execute_approved_refund(approval_id). The second tells the model this is for refunds, approval must already exist, the amount is not freely invented, and execution is not a generic transaction reversal. Good tool design wraps technical capability in a business-meaningful interface, and shapes the toolset around the task: reading, analysis, drafting, approval, and execution as separate, explicit actions.

A well-designed tool definition covers far more than a name and a function signature:

1. 01Name. Specific and action-oriented: get_customer_profile, not manage_customer; calculate_refund_eligibility, not finance_action. The model uses the name as part of its decision — and so do reviewers and auditors.
2. 02Purpose and description. “Retrieve verified order status from the order-management system” beats “gets order info.” The description says when to use the tool, what it returns, and what it does not return.
3. 03When to use — and when not to. The “do not use when” section is usually missing, and it is what prevents the model from forcing the wrong tool into service.
4. 04Inputs and input schema. Clear, minimal, typed parameters the harness can validate before execution. A tool that accepts a vague field called data is hard to use safely.
5. 05Output and output schema. Structured data, not vague prose — supporting consistent observations, auditability, evaluation, and human review.
6. 06Examples. Especially useful when tools are similar.
7. 07Error states. customer_not_found, access_denied, invalid_amount, duplicate_request. “Something went wrong” gives the agent no useful next step.
8. 08Permissions. Who may call it, under which identity — enforced by the harness and downstream systems, not merely described in the prompt.
9. 09Side effects and reversibility. Reading a profile changes nothing; sending an email cannot be unsent; a CRM update is reversible only if the previous value is stored. Reversibility should influence approval requirements.
10. 10Approval requirement. “Required when amount > €100” — enforced outside the model.
11. 11Source authority. Information tools should label their output: source, authority level, timestamp, effective date — so the model can weigh observations correctly.

Good tools versus bad tools

The contrast is clearest in examples. manage_customer(data) is a bad agent tool: can it read, write, delete, send messages, issue refunds? What fields are needed? What permissions apply? The better design separates the work — get_customer_profile, get_order_status, retrieve_refund_policy, calculate_refund_eligibility, draft_refund_response, submit_refund_for_approval, execute_approved_refund. Each tool has a clear job, and the sequence creates natural control points:

Read -> Calculate -> Draft -> Approve -> Execute

The same logic applies to power tools. run_shell_command(command) can read files, delete files, install packages, and exfiltrate data; some coding agents need it, but heavily sandboxed. For many enterprise workflows, a narrower tool is safer: write_report_file restricted to an allowed directory, allowed file types, and no overwriting of approved reports. And approve(data) — approving what, by whom, with what evidence? — should be request_finance_approval with a business case, the requested action, the financial exposure, and a risk summary.

The most important distinction in tool design is read versus write — but risk climbs in finer steps than that. Read tools answer “what is true in the system?” and are often the right starting point, though read-only does not mean risk-free: a read tool can expose personal data, contracts, and strategic plans. Analytical tools transform information, and a wrong calculation produces a wrong recommendation — test them like production software. Drafting tools prepare outputs without committing them, one of the safest ways to introduce agentic capability. Write tools change internal systems; external action tools affect customers, partners, and money; and high-impact execution tools can produce large or irreversible consequences.

Granularity and semantic clarity

Broad tools mean fewer definitions and flexible behaviour — and hidden side effects, unclear permissions, and harder audits. Narrow tools mean clear purpose, easier validation, and safer approval gates — at the cost of more definitions and orchestration, and possible tool-selection confusion if many overlap. The rule: the more consequential the action, the narrower and more explicit the tool should be. A public web search can stay broad; execute_approved_refund should execute exactly one previously approved refund and nothing else.

Related is semantic clarity: a tool should match a meaningful business action. Not post_transaction(payload) but execute_approved_refund(approval_id); not update_record(table, id, fields) but update_customer_contact_preference(customer_id, channel, preference). Business-meaningful names help the model — and compliance, debugging, and human review.

A model sees the tool name, description, and schema as part of its context, so tool descriptions deserve the same care as prompts — a bad tool description is a bad context object. And the schema is not just validation; it is guidance. A schema with retailer_id, a controlled promotion_type, and an effective_date teaches the model what information matters, while giving the harness deterministic validation points. Good parameter design prevents whole classes of error:

1. 01Use explicit fields. run_margin_simulation(product_id, retailer_id, discount_percentage, …), not run_analysis(input).
2. 02Use controlled values. reason: damaged_goods | missing_item | late_delivery, not free text meaning anything.
3. 03Avoid unnecessary free text. For high-risk tools, structured fields beat “refund the customer because the package was damaged.”
4. 04Require identifiers, not names. customer_id: CUST-80291, not customer_name: Sara Smith. With only a name, the agent should first call a lookup tool and verify identity.
5. 05Avoid hidden defaults. check_inventory(product_id) silently assumes a location, date, and inventory definition. Make them parameters.
6. 06Make units explicit. amount plus currency; lead_time_days, not lead_time.
7. 07Use safe defaults. send_mode=“draft” rather than send_immediately=true. For agents, the safest default is usually: prepare, do not execute.

Tool outputs are observations

In a ReAct-style agent, the tool result becomes the observation the next decision depends on — so outputs must be designed for reasoning. “Customer is fine” and “promotion looks good” are dead ends. A good observation carries status, identifiers, values, source, and timestamp; a good analytical output carries the scenario, the expected range, the main driver, and the sensitivity. And strong outputs separate the categories the model tends to blur:

Verified fact:   Retailer display fee is €68,000.
Estimated value: Expected uplift range 18%–26%.
Assumption:      Cannibalization estimated from
                 comparable promotions.
Warning:         15% scenario is negative in
                 most cases.
Next step:       Run 10% discount alternative.

Error handling is tool design. “Error” teaches the agent nothing; a structured error carries a type, a message, whether it is recoverable, and a recommended next step. A no-result error that lists the searched fields and possible causes — retailer stored under the parent company, date range too narrow — turns a dead end into a recovery path. Errors fall into classes that need different responses: input errors (fix the parameters), permission errors (escalate), business-rule errors (request approval), system errors (retry), no-result errors (reformulate or ask), and conflict errors (re-check state). The harness should guide recovery; the model should not blindly repeat failed calls.

Three companions to idempotency. Side-effect confirmation: the agent should not assume an action succeeded — an email tool returns sent status, message ID, recipient, and timestamp, and the final response is based on confirmed outcomes, not intended ones (“the refund tool confirmed REF-99281 for €47.80,” not “I have refunded the customer”). Retry policy: read tools retry safely; reservations and internal updates retry with caution; payments, emails, deletions, and external submissions are never retried blindly. Timeouts: a customer lookup gets seconds, a simulation a minute, a human approval two days — and after timeout the system needs a policy: retry, fallback, pause, escalate, or fail gracefully. A tool that hangs indefinitely breaks the agent loop.

Agents should not inherit broad human permissions by default; they should receive task-specific ones. A support agent may need to read profiles, check orders, draft responses, and submit refund requests — not export all customer records, delete orders, or send arbitrary emails. Three related anti-patterns: excessive functionality(the summarization agent’s email tool can also send, delete, and forward), excessive permissions (the recommendation agent’s database credential can update prices and delete rows), and excessive autonomy (the agent can delete documents on a model-generated interpretation, with no confirmation, preview, or reversible staging).

The strongest control pattern is the approval gate: draft_action → request_approval → execute_approved_action. The model never directly executes the sensitive step, and the draft becomes a reviewable artifact. But approval is only useful when it is meaningful: “approve agent action?” supports nothing. A strong approval presents the proposed refund, the reason, the evidence, the applicable policy, and the alternatives — approve, replace, request more evidence, reject. Human involvement should be part of the tool architecture (prepare_approval_packet, escalate_to_legal, pause_for_customer_confirmation), not bolted on afterwards.

Tools are context objects

Every tool definition consumes context, and fifty definitions can crowd out task evidence. Tool availability is a context-engineering decision: expose only task-specific tools, group tools by stage (show read tools during investigation, drafting tools during resolution, execution tools only after approval), use tool search against a registry instead of loading hundreds of definitions, and hide write tools until the workflow state allows them. Sequencingbelongs in the harness, not the model’s memory: if state is not approved, execute_approved_refund is simply not callable. And tools should update state as they run — drafted, awaiting approval, executed — which makes the process auditable and resumable.

The wider tool family

• Memory tools shape future behaviour, so the model should not freely write permanent memory: propose_memory_update → validate → store_approved_memory. A bad memory tool causes long-term contamination.
• Retrieval tools should return source, date, version, authority, and whether the document is current or archived. Retrieval is not just search; it is evidence construction.
• Code execution belongs in a sandbox with defined runtime, file access, network rules, resource limits, and output capture.
• Browser and computer use are very broad tools for when no API exists: domain allowlists, read-only modes, confirmation before form submission, no secrets entry, session isolation.
• Specialist agents as tools (forecasting_agent, legal_review_agent) are powerful but must not become black boxes: clear input and output contracts, authority limits, uncertainty reporting, escalation conditions.

All of this converges on the idea of a tool contract: what the tool does, requires, returns, may change, cannot do, when to use it, when not to, who may use it, and how failure is reported. A tool without a contract is not production-ready. And every call must be observable — tool name, caller, identity, parameters, permission decision, approval status, result, latency, cost, correlation ID — because if a tool changes the world, the organization must be able to reconstruct what happened.

1. 01Vague tool names. process_data, manage_order, do_action. Fix: action-specific names.
2. 02Overlapping tools. get_customer, lookup_customer, search_customer, find_customer_profile — the model chooses inconsistently. Fix: merge or clarify boundaries.
3. 03Hidden side effects. check_availability sounds like a read but also reserves inventory. Fix: name the side effect, or separate check from reserve.
4. 04Open-ended input fields. instruction: string lets the model pass arbitrary commands. Fix: structured parameters, controlled values.
5. 05Overbroad permissions. The tool can do more than the agent needs. Fix: least privilege, task-specific credentials.
6. 06Ambiguous outputs. “Approved.” By whom? For what? Until when? Fix: structured status with approver, amount, ID, expiry.
7. 07No error semantics. “Failed” — retry, ask, or stop? Fix: categorized errors with recovery paths.
8. 08No idempotency. A repeated transactional call duplicates its effect. Fix: idempotency keys.
9. 09No confirmation of side effects. The model assumes success. Fix: return the confirmed environmental outcome.
10. 10Tools exposed too early. Execution tools visible before investigation and approval complete. Fix: expose by workflow state.
11. 11Tools exposed to the wrong agent. A research agent with production write tools. Fix: separate roles and permissions.
12. 12Tool results containing untrusted instructions. A retrieved page tells the agent to ignore its rules. Fix: label external content untrusted, sanitize, validate actions outside the model.

Tool evaluation is how these surface before production. Test tool selection (known correct sequences, plus negative cases: an apology email needs no refund execution), parameters (wrong IDs, missing currency, amounts copied from user claims instead of system records), observation interpretation (refund_eligible with approval_required must lead to an approval request, not immediate execution), and failure cases (invalid IDs, timeouts, duplicates, prompt injection). The goal is not to see whether the happy path works, but whether the agent stays safe when the path is messy — and to distinguish a weak model from a confusing tool.

Consider the Promotion-to-Profit agent: should we run a 15% discount on family-size yogurt at Retailer A next quarter? A good toolset splits cleanly across the risk ladder — read tools (find_comparable_promotions, retrieve_retailer_terms, check_inventory_availability, check_production_capacity), analytical tools (estimate_baseline_demand, run_promotion_uplift_model, simulate_promotion_margin), drafting tools (prepare_finance_approval_packet, draft_retailer_proposal), and one execution tool (submit_approved_promotion_plan) that validates the scenario ID, finance approval, supply feasibility, notice period, and authorized user before anything happens.

Tool: simulate_promotion_margin

Purpose:  Expected incremental contribution
          profit for a promotion scenario.
Use when: Baseline, discount, margin, uplift,
          cannibalization, and retailer fee
          are available.
Do not use when:
          Retailer fee is missing or baseline
          has not been estimated.
Output:   contribution range, break-even
          uplift, sensitivity drivers,
          assumptions, warnings
Risk:     Analytical. Does not execute.
Errors:   missing_retailer_fee,
          invalid_discount_range, ...

The nominal sequence runs from comparables through simulation to approval packet — but the agent may adapt: if retailer terms reveal a large fixed display fee, it can evaluate a lower discount before checking capacity. The toolset gives flexibility; the workflow and permissions provide control. The same pattern shapes other domains:

• Customer support: identify → inspect → check policy → calculate → draft → approve → execute, instead of one customer_admin_tool.
• Software engineering: list_files, read_file, search_code, edit_file, run_tests are the core; shell, package installs, and deployment are sandboxed, branch-restricted, and review-gated. The model can write code; tool design determines where that code can go.
• Procurement: the supplier-risk agent reads questionnaires, compares terms, and prepares risk assessments — it prepares the decision; a human owns approve_supplier.
• Revenue operations: update_account_research_notes is allowed; change_opportunity_stage is riskier; delete_opportunity is not on the menu. Tool design reflects business impact.

Autonomy = model decision power + tool capability + permission scope. The real control is not a prompt that says “do not do anything risky.”

A good toolset creates constrained agency: too constrained and the agent cannot solve real tasks; too open and it can cause damage; well constrained and it makes useful progress inside clear boundaries. Tool design is the art of choosing that middle ground.

Seven questions to ask of every tool before exposing it:

1. 01Task fit. Does the tool match a real task the agent must perform — or is it exposed merely because it is technically available?
2. 02Operational boundary. What exactly can it do, and what can it not do?
3. 03Output quality. Does it return structured, source-aware observations that support the next reasoning step?
4. 04Least privilege. Does it have only the permissions required?
5. 05Known failure modes. Errors, retries, timeouts, partial success, recovery — all defined?
6. 06Idempotency and impact. Can the action be safely repeated? What are the side effects? Can it be reversed?
7. 07Traceability. Can humans reconstruct who called it, why, with what inputs, and what happened? If not, it is not enterprise-ready.

Six mental tests keep the framework honest:

• The dangerous intern test. Would you give this tool to a bright intern who sometimes misunderstands instructions? “Delete any files you think are unnecessary” — no. “Prepare a deletion proposal for human review” — yes.
• The junior developer docstring test. Could a junior developer use the tool correctly from its description alone? If not, the model will struggle too. It is reading the description, not your mind.
• The blast radius test. What is the worst outcome of an incorrect call? Low for search, high for payments, very high for shell, catastrophic for production deployment. Risk should determine control.
• The repeat call test. What happens if it runs twice? If the answer is dangerous: idempotency, duplicate detection, state checks, approval.
• The wrong target test. What if it hits the wrong customer, product, file, or contract? Exact IDs, identity verification, previews, reversible staging.
• The untrusted observation test. What if the result contains malicious instructions? Untrusted-content labeling, no direct execution from retrieved text, injection testing.

The tool-design maturity model

The platform level is where governance becomes explicit. Versioning: traces must record which tool version ran, or past decisions cannot be reproduced. Deprecation: a forgotten tool connected to an outdated system is a hidden vulnerability. Registries: a governed catalog of names, schemas, owners, risk levels, and evaluation status. Ownership: finance owns refund execution, supply chain owns inventory availability, legal owns contract retrieval — tools without owners become technical debt. And governance answers who can create, approve, expose, test, monitor, and remove tools; without it, tool sprawl becomes an agent reliability problem.

Ten tool security principles

1. 01Least privilege. Expose only what the agent needs.
2. 02Narrow functionality. Prefer specific tools over open-ended ones for high-risk operations.
3. 03User-context authorization. Run actions in the proper user or service context.
4. 04Human approval for high-impact actions. The model alone must not authorize major consequences.
5. 05Complete mediation. Every tool call is checked against policy.
6. 06Structured inputs and outputs. Avoid arbitrary commands where structured parameters are possible.
7. 07Audit logging. Record what happened.
8. 08Rate limiting. Limit damage from loops or compromise.
9. 09External-content isolation. Untrusted tool results must not become trusted instructions.
10. 10Sandbox broad tools. Shell, browser, and computer-use tools need isolation.

For a first enterprise agent, start small: search_policy, retrieve_customer_record, get_order_status, calculate_eligibility, draft_response, request_human_approval. Avoid starting with send_email, issue_refund, delete_record, run_shell_command, or update_any_database_table. Begin with read, analysis, and drafting; add execution only after evaluation.

Add a new tool when the agent repeatedly needs a capability, current tools force awkward workarounds, the action can be clearly scoped, and value justifies risk — not simply because it is technically possible. Remove or hide a tool when it is rarely used, overlaps with another, causes frequent model errors, has an unclear owner, or is not covered by evaluations. Pruning is part of tool design. A production-ready tool is clear, scoped, typed, permissioned, observable, recoverable, safe, and evaluated; a tool that lacks these may serve a prototype, but it is not ready for high-trust production use.

Tool design also completes the picture drawn by the rest of this series. The harness validates and executes what the model proposes. Tool definitions, outputs, errors, and availability are all context — tool design and context engineering are inseparable. Tools provide ReAct’s “act” step and their results provide the “observe” step, so bad tools break the loop from both ends. And the draft-approve-execute pattern is scaffolding in tool form: the tool architecture can preserve human agency, or remove it. That is a design choice.

What is a tool in AI agents?

A structured capability that a model can call to retrieve information, perform computation, interact with software, or take controlled action in an external system.

Is a tool the same as an API?

No. An API is a technical interface. An agent tool is an API, function, or workflow endpoint packaged so a model can understand, select, and use it safely.

What is tool calling?

The process by which a model requests that a specific tool be invoked with specific arguments. The harness executes the tool and returns the result to the model.

Why should tools be narrow?

Narrow tools reduce ambiguity, simplify validation, improve permissions, and lower the chance of unintended actions. But tools can be too narrow: too many tiny tools overwhelm the model and increase orchestration complexity. The right granularity depends on task complexity and risk.

Why is idempotency important?

Agents may retry or repeat actions. Idempotency prevents duplicate side effects, such as issuing the same refund twice.

Should agents have shell or browser tools?

Only when necessary, and with strong sandboxing, permissions, logging, and approval for risky actions. Broad tools increase the blast radius of mistakes.

What makes a tool enterprise-ready?

A clear contract, typed inputs and outputs, scoped permissions, structured errors, side-effect controls, observability, evaluation, and ownership.

What is the biggest tool-design mistake?

Exposing broad, powerful, poorly described tools to a model and expecting instructions alone to keep the system safe.

Tools are where agentic AI becomes operational. Without tools, a model can only think and speak. With tools, it can retrieve, calculate, inspect, draft, update, communicate, and execute. That is the promise — and the risk. A tool gives the model capability; a toolset defines the agent’s action space; a permission model defines its authority; a harness controls its execution; an observation becomes the basis for the next decision. Tool design sits at the center of agent architecture.

The strongest agent systems are not those with the most powerful models or the largest number of tools. They are the systems with the clearest, safest, most task-appropriate tools: understandable to the model, meaningful to the business, narrow enough to control, structured enough to validate, observable enough to audit, and useful enough to justify their risk. The model provides reasoning. The harness provides control. Context engineering determines what the model sees. Tool design determines what the agent can do.

Do not give an AI agent every possible action. Give it the right actions, with the right boundaries, at the right moment, under the right controls. That is how models get reliable hands.