Integration first: agents are only as good as their APIs

Much of the conversation about AI agents revolves around the model: which one reasons better, which makes fewer mistakes, which costs less. It is a fair question, but in IT operations it is rarely the one that decides the outcome. A triage agent that cannot read the change history, or a rightsizing agent that cannot query a resource's actual usage, does not improve with a more capable model. It just reasons better about incomplete data.

An agent's value is bounded by the tools it can use, and those tools are, in almost every case, APIs of systems that already exist: the service management platform, the CMDB, the cloud console, the observability tool, the automation orchestrator. If those APIs are incomplete, ambiguous or fragile, so is the agent. That is why we propose reversing the usual order: integration first, agent second.

From contract to tool

An agent does not read an API's code or its developer portal. It reads a structured description of each tool: name, purpose, input parameters and the shape of the response. In the Model Context Protocol (MCP), for example, each tool is published with a description and a JSON input schema, and it can also declare an output schema to validate structured results. That description is everything the model knows about the tool.

The most reliable way to produce good descriptions is to start from contracts that already exist, or that you should have anyway:

• OpenAPI describes HTTP APIs: paths, operations, parameters, request and response schemas, security. Version 3.1 bases its schemas on JSON Schema 2020-12, the same dialect MCP assumes by default for tool schemas in its 2025-11-25 revision.
• AsyncAPI describes message-driven and event-driven APIs: channels, send and receive operations, and messages. It is the reference for documenting what an agent can listen to (monitoring events, state changes), not just what it can request.

With a well-written contract, exposing an operation as a tool is largely a translation exercise. Without one, each tool becomes a custom integration, with hand-written descriptions that go stale as soon as the API changes.

An important nuance: not every API operation should become a tool. Exposing hundreds of generic operations forces the model to choose among many similar options and widens the risk surface. It is better to design a few tools, with task-oriented names and descriptions ("get recent changes for a service") instead of mirroring the API's internal structure.

What makes an API ready for agents

An API designed for system-to-system integration or for a web interface does not always serve an agent well. A traditional program follows a fixed path written by a developer; an agent decides at each step what to call, with which parameters and what to do with the response. That requires properties worth reviewing explicitly.

Criterion	What to check	Why it matters to an agent
Published contract	Current OpenAPI or AsyncAPI, versioned and validated against the real API	It is the source of the tool description
Useful descriptions	Each operation and parameter explains what it does, valid values and units	The model picks the tool and builds parameters from the text
Reads separate from writes	Query operations with no side effects; explicit, bounded writes	Lets you enable reads first and govern writes separately
Idempotency	Retrying a write with the same key does not duplicate the effect	Agents retry after failures or ambiguous responses
Clear errors	Correct HTTP codes and a structured body with cause and possible fix	The agent can correct parameters instead of insisting or guessing
Pagination	Stable cursors, bounded page size, end indicator	Avoids huge responses that do not fit in the model's context
Usage limits	Documented limits, 429 response with wait time	An agent in a loop must not degrade the system for everyone
Filters and fields	Queries by criteria and field selection	Less irrelevant data, lower cost and less exposure
Granular authorization	Permissions per operation and resource, audience-bound tokens	The basis for least privilege per tool
Traceability	Correlation ID accepted and returned	Links the agent's call to the audit log

You do not need to meet every criterion to start. You do need to know which ones are missing, because each gap turns into a limitation of the agent or an extra control that has to be added outside the API.

Reads before writes, and idempotency always

The separation between reads and writes is the criterion that weighs most in practice. An agent that only reads (summarizes incidents, correlates signals, proposes actions) adds value with bounded risk. An agent that writes also needs approval, limits and logging, as we explain in guardrails for AI agents.

That is why we recommend that each tool declare its effect. MCP offers annotations for this, such as readOnlyHint, destructiveHint and idempotentHint. They are useful for the interface and for the model, but the specification treats them as untrusted hints unless the server is trusted. The real control lies in the API's permissions, and in the read tool using credentials that cannot write.

Idempotency deserves its own mention. An agent may retry an operation because it got no response, because the result looked ambiguous or because it restarted the task. If creating a ticket or scaling a resource is not idempotent, every retry duplicates the effect. The usual pattern is for the client to send a unique key per operation and for the API to return the same result if it receives that key again. For operations that by nature cannot be idempotent, require human approval.

Errors, pagination and limits a model can understand

A developer who gets an error reads the documentation and fixes the code. An agent only has the error message. If the API answers "Error 500" to a malformed parameter, the agent has no way to know what to change.

Two references help. RFC 9457 (Problem Details for HTTP APIs) defines a standard error format with type, title, status and detail that a model can interpret. And the MCP specification distinguishes protocol errors (unknown tool, malformed request) from tool execution errors, which are returned in the result flagged with isError. The latter should contain actionable information so the model can correct itself and retry with different parameters, and the specification recommends that the client pass them to the model.

Pagination works the same way. A query that returns ten thousand records does not fit in the model's context and, even if it did, would be expensive. The API should offer pagination with stable cursors and filters that let the agent ask only for what it needs. MCP uses the same approach for its own lists: opaque cursors and a page size set by the server.

Finally, usage limits. A misconfigured agent can fall into a loop of calls. The API should answer with status code 429 (Too Many Requests, RFC 6585) and, when possible, state how long to wait with the Retry-After header. The tool, in turn, should honor that instead of retrying immediately.

API inventory and priorities with Value × Complexity

Before deciding which agent to build, you need to know which APIs exist. We recommend an inventory that records, for each relevant system: whether it has an API, whether it has a published contract, which read and write operations it offers, how it is authorized, who owns it and how many criteria from the table above it meets. That inventory often shows the bottleneck is not the agent, but two or three systems without a usable API. It also reveals data problems worth addressing first, as we discuss in AI-ready data.

To decide which integrations to build or improve first, we use the same framework as for the automation backlog, described in prioritizing automation by value and complexity. Each candidate is documented in a profile and scored from 1 to 5 on two axes:

• Value: the average of effort saved, reduction of risk and errors, impact on the customer or the SLA, and contribution to compliance or audit. Here the value is that of the agent use cases the integration enables.
• Complexity: the average of number of systems and integrations, process variability, quality of available data and access, risk of the change in production, and dependence on third parties.

With a cutoff at 3, each integration falls into a quadrant:

1. Quick wins (high value, low complexity): for example, exposing as read-only tools the queries of an API that already has a contract. These go first.
2. Strategic bets (high value, high complexity): for example, a write API on a system with no contract or idempotency. These are split into smaller deliveries, starting with reads.
3. Opportunistic fixes (low value, low complexity): done when there is spare capacity.
4. Drop or redesign (low value, high complexity): not integrated as they are; simplify the process or the system first.

Since value and complexity change (a vendor publishes an API, a system is replaced), the inventory and the prioritization are reviewed periodically, for example every quarter.

Where to start

We recommend three concrete steps. First, choose an agent use case with clear value and list the operations it needs. Second, assess the APIs involved against the criteria table and close the critical gaps (contract, clear errors, read and write separation) before writing the agent's first instruction. Third, expose the tools through a control point with identity, policy and logging, as we describe in governing MCP agents.

Integrations that enable writes on critical systems, or that expose personal data, should be reviewed with Architecture and Security before they reach production.