Tool Contracts Are More Important Than Tool Count

Agent demos love abundance.

Connect the model to email, tickets, chat, cloud infrastructure, payments, analytics, documents, and thirty internal services. Put every action into one searchable catalog. Ask the agent to run the business.

The result looks powerful right up to the moment a tool called update_record accepts twelve optional fields, returns success: true, and leaves everyone arguing about what actually changed.

An agent does not become dependable because it can call more functions. It becomes dependable when each function has semantics the runtime can enforce and the model can understand.

The quality of the coupling matters more than the size of the toolbox.

A Schema Is Not a Contract

JSON Schema can describe the shape of an input. It cannot, by itself, explain the meaning of an operation.

Consider a tool named send_message. Does it send immediately or create a draft? Can it be retried? Does a timeout mean the message was not sent? Does it accept external recipients? Is the returned identifier a delivery receipt or merely a queued request? Can the action be reversed?

Those questions determine whether an agent can use the tool safely. None is answered by knowing that recipient and body are strings.

A useful tool contract describes preconditions, authority, effects, retry behavior, failure states, and completion evidence. The natural-language description helps the model select the tool. The machine-enforced policy keeps that selection inside reality.

Name Tools After Intent

Generic CRUD tools force the model to reconstruct business rules from low-level operations.

update_customer may be able to change an address, disable an account, modify a credit limit, or erase a consent flag. Those actions have different authorization, review, and audit requirements. Combining them into one flexible function produces a convenient API and an ambiguous capability.

Prefer tools that express consequential intent: draft_customer_reply, request_credit_limit_review, set_shipping_address, revoke_marketing_consent. Their names and parameters narrow the decision before execution begins.

This is not an argument for one tool per database column. It is an argument for aligning the tool boundary with the business boundary. If two operations require different permission, verification, or recovery, they probably deserve different contracts.

Make Effects Explicit

Every tool should declare its effect class.

A read retrieves state. A proposal creates an artifact without applying it. A set operation moves a resource toward a declared state. An effect operation sends, charges, publishes, deletes, or otherwise creates an external consequence.

The harness can treat those classes differently. Reads may be automatically retried. Proposals can run in parallel. Set operations can verify the resulting state. Effect operations may require an idempotency key, approval, and reconciliation.

Without effect metadata, the runtime relies on the model to infer risk from verbs. That is fragile. sync, apply, and resolve can hide enormous consequences behind reassuring names.

Effects belong in the tool definition where policy can inspect them.

Return States, Not Vibes

Many agent tools return prose such as “The operation appears to have completed successfully.”

That sentence is friendly to read and difficult to orchestrate. Did the provider accept the request? Is the effect visible? Is it still processing? Can the call be retried? What should happen next?

A durable result separates transport from outcome. It might report accepted, pending, completed, rejected, or outcome_unknown, along with an operation identity, canonical parameters, timestamps, and a method for reconciliation.

Typed failure matters just as much. permission_denied should not trigger the same behavior as rate_limited. validation_failed should not be retried with exponential backoff. outcome_unknown must not be translated into “try again” for a payment or external message.

The agent can still explain the result in natural language. The workflow should not depend on interpreting that explanation.

Separate Preparation From Commitment

Consequential tools are easier to govern when they expose a two-stage shape.

The preparation stage resolves targets, validates parameters, calculates the expected change, and produces a reviewable artifact. The commitment stage applies that exact artifact under the required authority.

For a deployment, preparation may identify the service, artifact digest, environment, migration plan, and rollback conditions. For an email, it may produce the exact recipients, subject, body, and attachments. Human approval can bind to that artifact instead of a vague future intention.

If anything material changes, the artifact identity changes and the approval no longer applies. This turns human approval into a real boundary rather than a button beside an evolving action.

Constrain Outputs at the Source

An agent should not receive an entire customer record when the decision needs an account status and renewal date.

Tools should return the smallest useful representation, with provenance and freshness attached. This reduces privacy exposure, prompt-injection surface, context pressure, and the chance that an irrelevant field becomes salient.

The same rule applies to write capability. A repository tool scoped to one workspace is better than a generic shell with a warning in its description. A ticket tool that can comment but not close is safer when the task only needs a comment.

Least privilege should be visible in the contract and enforced by the connector. Telling the model “do not use the extra fields” is not a permission system.

Version Meaning, Not Just Shape

Tool interfaces evolve. A field changes from optional to required. A default changes. A provider starts sending immediately where it once created a draft.

The dangerous changes are semantic, even when the schema remains valid.

Version contracts when behavior changes. Record the contract version in traces and evaluation cases. Support a migration period where old and new behavior can be compared. Do not let a connector update silently redefine what an established agent action means.

This is especially important with third-party tools. The wrapper is the product boundary. It should absorb provider quirks and expose a stable internal contract rather than leaking every external API directly into model context.

Design for Discovery Without Confusion

Large tool catalogs create a selection problem. Similar names compete for attention. Tool descriptions consume context. The model may choose a broad general function over the narrow safe one because it appears earlier or sounds more capable.

Discovery should be staged. Expose a small capability index first, then load the relevant tool family when the task enters that domain. Group mutually exclusive operations and make their differences explicit. Hide tools the current route cannot authorize.

The goal is not to show the model everything it could ever do. It is to make the right action easy to select in the current state.

Fewer visible tools can produce more practical capability because selection becomes clearer and policy becomes enforceable.

Test the Contract at Its Worst Moment

Tool tests should go beyond valid arguments and happy responses.

What happens when the provider commits and the connection drops? When two workers call with the same intent? When an approval expires between preparation and commitment? When returned content contains hostile instructions? When the provider changes a default? When the agent supplies a valid identifier from the wrong tenant?

The correct behavior should emerge from the contract and runtime, not from the model improvising around an error message.

Evaluation should also test tool choice. Give the agent several plausible capabilities and verify that it selects the narrowest one, supplies evidence, and stops when the required authority is unavailable.

Reliable Agency Lives at the Interface

Models will continue to improve at discovering and invoking tools. That makes weak contracts more dangerous, not less.

Name tools after intent. Declare their effects. Return typed states. Separate preparation from commitment. Constrain data and authority. Version semantics. Test ambiguous outcomes.

A vast catalog can make an agent look capable in a demo. A small set of exact, enforceable contracts is what lets it do useful work when the result matters.