Skip to content
← All guides

Building Agents

Flagship field guide

MDX

Designing Tools That Agents Can Use Reliably

Principles for tool names, parameters, responses, errors, idempotency, and safe execution.

4 min readAgentic Systems Editorial Team

Editorial review: clarity, operational relevance, safety boundaries, and source quality.

Make the purpose unmistakable

Use a specific action-oriented name and describe when the tool should and should not be used. Avoid several overlapping tools that force the model to guess among nearly identical choices.

Tool boundaries should match user intent and organizational authority. A model should request `schedule_existing_customer_visit`, not orchestrate raw calendar writes and database updates independently. Domain-level tools reduce the number of decisions and give the application one place to enforce invariants.

Keep inputs narrow

Prefer enums, required identifiers, and small structured objects over free-form blobs. Validate every field and return errors that explain how the request can be corrected.

Every optional parameter increases ambiguity. Prefer a few required fields, enums with meaningful values, and server-side defaults that are safe and visible. Validate cross-field rules after schema parsing—for example, an end time must follow a start time and the requested account must belong to the authenticated user.

Design for retries

Network and model failures make repeated calls inevitable. Use idempotency keys for writes, expose the resulting state, and distinguish safe retries from actions requiring fresh approval.

Retries are part of normal operation. Read tools can usually be repeated; writes need idempotency keys, explicit pending states, and postcondition reads. Return whether an error is invalid, denied, temporary, or indeterminate. An indeterminate write must be reconciled before any retry to avoid duplicate effects.

Practical example

A reliable meeting scheduler

The tool accepts participant IDs, a bounded time window, duration, and timezone. It checks calendar access and returns candidate slots without booking. A separate booking tool accepts a chosen slot, approval token, and idempotency key, then returns the event ID and final attendees. This makes availability exploration reversible and the committed action narrow and auditable.

Field checklist

Apply it in practice

  • Design around domain actions, not raw APIs.
  • Minimize optional and free-form inputs.
  • Validate permissions and cross-field semantics.
  • Define retry behavior for every error and write.

Decision framework

Questions to answer before you build

Reliable tools compress complex infrastructure into narrow, intention-level actions with explicit side effects, typed errors, and safe retry behavior.

Does the boundary match user intent?

Expose a complete domain operation rather than forcing the model to coordinate raw database and API calls that must remain consistent.

Can optional inputs be removed?

Every optional field expands ambiguity. Use required fields and safe server defaults, then expose a separate tool for meaningfully different actions.

Is the operation retry-safe?

Reads are usually repeatable; writes need idempotency keys, pending states, and reconciliation when the result is unknown.

Common failure signals

Watch for these warning signs

  • Creating many overlapping tools with subtle naming differences.
  • Returning whole records when the next decision needs only a few fields.
  • Treating network timeout as proof that a write did not happen.

Field manual

Implementation blueprint

  1. 01

    Start from user intent

    Name the complete domain action the user expects, then keep database and API coordination behind that boundary.

    Deliverable: A small tool inventory with no overlapping purposes.

  2. 02

    Separate preview from commit

    Let the agent prepare and inspect a proposed change without write permission; execute only with fresh authority.

    Deliverable: Distinct propose and execute contracts for consequential actions.

  3. 03

    Model failure explicitly

    Return invalid, denied, temporary, and indeterminate outcomes with safe recovery guidance.

    Deliverable: An error taxonomy that prevents blind retries.

  4. 04

    Verify the postcondition

    After a write, return the resulting authoritative record or re-read it independently.

    Deliverable: Evidence that the intended state—not merely the request—was completed.

Reusable working artifact

Tool contract specification

A tool definition should document authority and operational behavior as carefully as its input schema.

TOOL: propose_refund
PURPOSE: Prepare a policy-valid refund proposal; does not move money.
PRECONDITIONS: Authenticated customer; order belongs to account.
INPUT: { order_id, reason_code, requested_amount }
VALIDATION: amount > 0; currency from order; reason is allowed for order state.
RESULTS:
  proposed  -> { proposal_id, approved_amount, expires_at, evidence[] }
  invalid   -> { field, code, recovery }
  denied    -> { policy_code, escalation_route }
  unavailable -> { retry_after, safe_to_retry }
SIDE EFFECTS: Creates an expiring proposal only.
AUTHORITY: Read order + policy; no payment permission.
OBSERVABILITY: task_id, actor_id, policy_version, latency, result_code.
IDEMPOTENCY: client_request_id deduplicates proposal creation.

Measurement

Operational scorecard

Selection clarityCorrect tool chosen when alternatives are availableOverlapping descriptions often cause errors before model capability does.
Argument validityCalls passing schema and semantic validationTrack syntax and business-rule failures separately.
Retry safetyDuplicate external effects under timeout and replay testsThe acceptable count for duplicate financial or public effects is zero.

Failure drills

Rehearse before the system has real authority

  • Replay the same write request with the same idempotency key and verify one external effect.
  • Return an indeterminate response after execution and require reconciliation before retry.
  • Request a resource owned by another user and confirm denial occurs outside the model.

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.

↑ Back to top