An AI agent that fails in a chat window is a bad demo. An AI agent that fails while calling a tool updating the wrong customer record, issuing a duplicate refund, deploying to production instead of staging, is an incident. The difference between those two outcomes rarely comes down to the model. It comes down to how the tool it called was defined.
Why loosely defined tools break at scale
Language models are flexible and probabilistic. APIs, databases, and billing systems are not, they expect exact types, exact permissions, and exact, repeatable behavior on every call. Wrapping an endpoint in a JSON schema and handing it to a model doesn't close that gap on its own. The model can still infer the wrong parameter, pick a plausible but incorrect action, or supply a value that passes schema validation while violating a business rule.
This compounds as the number of available tools grows. Berkeley Function-Calling Leaderboard data aggregated by Presenc AI shows frontier models holding 95–96% accuracy when selecting from a single tool, dropping to 85–91% at five tools, and falling to 65–78% once the toolkit passes twenty. Chain several of those calls into one workflow and the error rate compounds fast, a five-step process running at 90% per-call accuracy only completes correctly about 59% of the time end to end.
What a tool contract needs to specify
A reusable tool contract is closer to an API specification than a function signature. At minimum, it defines:
Name — action-oriented, stating exactly what the tool does
Purpose — when to call it, and explicitly when not to
Inputs — required and optional parameters, typed, with constraints
Outputs — a stable shape for both success and failure states
Side effects — read, create, update, or delete, stated plainly
Permissions — which identities or roles can invoke it
Safety controls — approval requirements, rate limits, validation rules
Failure handling — error codes, retry guidance, recovery paths
Version and owner — so it can change without breaking every consumer at once
Narrow tools outperform flexible ones
A single tool that accepts an action enum and an untyped data object is faster to build once, but every decision about intent gets pushed onto the model at call time. Compare:
{
"name": "manage_customer",
"action": "create | update | delete | refund | export",
"data": "anything"
}
against:
{
"name": "update_customer_contact",
"description": "Updates the email address or phone number for an existing customer. Do not use for billing, refunds, account deletion, or permission changes.",
"input": {
"customer_id": "string",
"email": "string | null",
"phone": "string | null"
}
}
The second version removes an entire category of ambiguity before the call is made. This holds across a toolkit generally: separate read tools from write tools, separate reversible actions from high-impact ones, and resist merging unrelated actions to keep a tool count artificially low.
Enforcing inputs instead of documenting them
Strict, typed schemas, JSON Schema, OpenAPI, or an equivalent, do enforcement work that prose descriptions can't. Required fields marked explicitly, enums for fixed options, format validation on emails and dates, numeric bounds, and rejection of unexpected properties all shrink the space in which a technically-valid call can still be practically wrong. Outputs need equivalent structure: a response that reports status, a resource ID, a reason, and a next action is something downstream systems can route deterministically. A generic error string is not.
The server is the security boundary, not the model
Identity checks, authorization, resource validation, and business-rule enforcement belong on the server side on every call, independent of anything the model claims about its own permissions. High-impact actions benefit from being split into stages rather than executed atomically, preview_refund, request_refund_approval, execute_approved_refund instead of a single send_refund tool. Write operations need idempotency keys so a retried call can't produce a duplicate record, and irreversible actions benefit from a dry-run mode that surfaces the effect before it happens.
Versioning and testing the contract itself
Contracts change. Fields get deprecated, new parameters get added, and older agents keep calling older versions until they're migrated. Treating a contract like a versioned API with a named owner, a deprecation timeline, and contract tests for both old and new versions prevents a schema change from silently breaking a workflow nobody remembered was still using it.
Testing needs to go past checking that an endpoint returns a 200. It should verify that an agent selects the correct tool for an ambiguous request, supplies valid arguments, handles missing or malformed input without a silent failure, retries safely, and respects permission boundaries across roles. Realistic traces, duplicate requests, stale resources, partial successes, slow dependencies, surface the failure modes a happy-path test never will.
Where this fits in the current shift toward contract-first agent design
A June 2026 survey of more than 1,300 practitioners by LangChain, reported via PromptSphere Hub, found 57% already running agents in production, with 32% still naming quality as their leading barrier to scaling further. That's shifted where engineering effort goes: orchestration frameworks like LangGraph and CrewAI now push explicit schemas and state machines rather than open-ended prompting, and AI development platforms, 8080.ai among them, alongside tools like Replit and Lovable increasingly generate structured API contracts and permission boundaries as part of initial system design instead of leaving contract work as cleanup after the code already exists.
Building a contract library instead of one-off integrations
The pattern that scales is treating contracts as shared infrastructure: a standard template, consistent naming conventions, published error codes, and a catalog of what already exists so teams stop rebuilding slightly different versions of the same tool. That catalog is what new agents plug into, rather than each integration reinventing validation, permissions, and error handling from first principles.
A contract doesn't make an agent smarter. It makes the boundary around what the agent is allowed to do explicit, testable, and safe to leave running unattended which, for anything touching real data or real infrastructure, matters more than the model underneath it.
Top comments (0)