The Agent Tool Catalog: How to Standardize Actions Without Killing Speed

Why agent tools need a product discipline

An agent becomes operationally useful when it can do more than generate text: query a customer record, create a refund, schedule a delivery or update a campaign. Each capability is usually exposed as a tool, wrapping an API, database operation or workflow. The temptation is to build these wrappers locally and quickly. That works for the first five tools. At 50, teams discover duplicate actions, inconsistent parameters and permissions that nobody can explain. At 500, a simple change to a billing API can break agents across support, sales and finance.

A tool catalog is the control plane for this growing action layer. It gives every reusable capability a canonical identity, owner, contract, risk level and operating history. Crucially, it is not merely a directory. A spreadsheet listing names and endpoints cannot tell an agent when to call a tool, prevent an excessive refund or prove that a deprecated version has no remaining consumers. The catalog must connect discovery, documentation, testing, deployment and governance.

The objective is not maximum standardisation. It is standardisation at the boundaries where inconsistency creates risk or slows reuse. Teams should remain free to experiment with prompts, orchestration and user experience. They should not invent five meanings for “customer_id” or five authentication patterns. The catalog converts those shared concerns into a paved road, allowing product teams to spend less time rebuilding plumbing and more time improving outcomes.

Define a contract agents can actually use

Every catalog entry needs a machine-readable contract and a human-readable operating guide. The contract should include a stable tool name, version, purpose, input and output schemas, authentication method, timeout, retry policy, idempotency behaviour and structured error codes. JSON Schema or an equivalent interface definition is preferable to prose alone. Constrained fields such as currency, country code and refund reason should use enums or validated formats. If an argument is optional, the contract must state what happens when it is omitted.

The description is part of the execution surface because models use it to select and invoke tools. “Updates an account” is dangerously vague. “Changes the billing address for an existing account; does not alter delivery addresses; requires explicit user confirmation” gives the model decision boundaries. Include positive and negative examples: when to use the tool, when not to use it and what prerequisite facts must be present. A useful benchmark is whether an unfamiliar engineer can predict the tool’s behaviour without reading its implementation.

Outputs also need discipline. Returning a free-form success message forces every consumer to parse language. A refund tool should return fields such as refund_id, status, amount, currency and expected_settlement_date. Errors should distinguish invalid input, missing permission, dependency failure and uncertain completion. That final state matters: if a payment provider times out after receiving a request, an automatic retry without an idempotency key could charge or refund twice.

Design the catalog around actions, not systems

Internal APIs are commonly organised around service ownership: CRM, payments, logistics and identity. Agents reason more effectively with task-oriented actions such as find_customer, issue_refund and reschedule_delivery. The catalog should therefore present a coherent action vocabulary while preserving links to the underlying systems. Exposing raw endpoints encourages agents to assemble brittle sequences and leaks implementation detail into prompts.

Granularity is a deliberate trade-off. A single universal “manage_order” tool may be easy to discover but difficult to constrain, test and authorise. At the other extreme, separate tools for every field mutation create choice overload. A practical rule is to group operations that share intent, permissions and failure modes. Viewing an order and cancelling one should be separate because their risk differs. Changing a delivery date and delivery window may belong together if both use the same validation and approval path.

Naming must be predictable. Use verbs for actions, stable nouns for domain objects and version identifiers for breaking changes. Maintain aliases only as migration aids, not permanent forks. Search metadata should include synonyms, business domains, required roles and common workflows. When two teams propose overlapping tools, the catalog review should decide whether to extend an existing contract, create a specialised action or retire one implementation. That small decision prevents years of duplication.

Build a testing ladder before production access

Tool tests must cover more than whether an endpoint returns 200. Start with contract validation: required fields, types, bounds and error shapes. Add deterministic unit tests for policy logic, integration tests against a sandbox and replay tests using sanitised production traces. Then evaluate agent behaviour: does the model choose the correct tool, populate arguments accurately, recover from safe failures and stop when approval is required? A technically flawless tool can still be operationally poor if its description causes selection errors.

Use measurable release gates. A low-risk read tool might require 99.5 per cent schema-valid calls across 1,000 evaluation cases and zero leakage of restricted fields. A payment action might demand 100 per cent enforcement of amount limits, idempotency under repeated requests and explicit confirmation in every high-risk scenario. Red-team cases should include prompt injection inside retrieved records, ambiguous customer identities, stale authorisation and malicious values embedded in tool outputs.

Production rollout should proceed through shadow mode, limited traffic and graduated permissions. In shadow mode, the agent proposes calls without executing them, allowing teams to compare intended actions with human decisions. At 1 per cent live traffic, monitor tool-selection accuracy, failure rates, latency and manual reversals before expanding to 10, 25 and 100 per cent. Every write tool needs a kill switch, and consequential actions should have a tested compensation path where technically possible.

Govern by risk tier, not committee instinct

A catalog becomes a bottleneck when every tool faces the same review. Risk-based tiers preserve speed. Tier 0 might cover public, read-only data; Tier 1 internal reads; Tier 2 reversible writes; Tier 3 financial, legal, security or externally visible actions. Low-risk tools can pass automated checks and owner approval within hours. High-risk tools should require security review, policy validation, scoped credentials, human-approval design and evidence from adversarial testing.

Each tier should define enforceable controls. A Tier 2 calendar tool may be allowed to create meetings but not invite external domains without confirmation. A Tier 3 refund tool might cap autonomous refunds at £50, enforce a £500 daily customer limit and route exceptions to an authorised employee. Put these limits in middleware or the tool implementation, not in prompts. Prompts guide behaviour; controls guarantee boundaries.

Ownership must be explicit. Every entry needs a business owner, technical maintainer, data classification, incident route and review date. Access should use short-lived, narrowly scoped credentials tied to the calling agent and user context. Log the request, validated arguments, policy decision, result, model and tool versions, while excluding secrets and unnecessary personal data. Governance then becomes observable engineering rather than periodic paperwork.

Make the paved road faster than the shortcut

Teams evade standards when compliance requires weeks of tickets. The catalog needs a self-service developer experience: a tool template, schema generator, local simulator, test harness, security defaults and one-command registration. A new low-risk tool should be discoverable in a development environment within a day. Automatic checks can reject missing owners, unbounded strings, undocumented errors or credentials embedded in configuration before a reviewer becomes involved.

Provide reusable adapters for common systems and concerns. Authentication, rate limiting, audit logging, input sanitisation, retries and tracing should not be reimplemented by every product squad. A standard wrapper can inject correlation IDs, enforce deadlines and translate provider errors into catalog-wide codes. This reduces code and creates consistent telemetry. It also lets platform teams patch a vulnerability once rather than coordinate changes across dozens of wrappers.

The catalog interface should serve both people and machines. Engineers need examples, changelogs, dependency maps and performance data. Agents need concise descriptions and schemas filtered to the current task and permissions. Do not place 400 tools into every model context; retrieval should shortlist perhaps five to 15 relevant actions. Fewer, better-matched tools reduce token cost and selection confusion while ensuring inaccessible capabilities never reach the model.

Operate tools through versions, metrics and retirement

A tool is a product with a lifecycle. Non-breaking additions, such as a new optional output field, can remain within a version if consumers tolerate them. Renamed fields, changed semantics or tighter required inputs need a new version and migration plan. Publish deprecation dates, identify active consumers from telemetry and provide automated compatibility reports. Never assume that an old tool is unused because its original team has moved on.

Measure the catalog’s value with operational and delivery metrics. Track reuse rate, median time to publish, percentage of calls using canonical tools, selection accuracy, schema-invalid calls, p95 latency, policy denials, incident rate and deprecated-version traffic. A catalog that grows from 100 to 300 entries while reuse falls may be accumulating duplication rather than capability. A healthier signal is fewer net-new tools supporting more workflows.

Review high-risk tools quarterly and lower-risk entries at a proportionate cadence. Retire tools that duplicate stronger alternatives, lack owners or fail reliability targets. Incident reviews should update contracts, evaluations and platform controls, not merely prompts. The successful catalog is neither a static registry nor a gatekeeping board. It is a living action architecture: strict about interfaces and safety, automated wherever evidence permits, and fast enough that teams choose it voluntarily.