What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
An agent-friendly API is one that a software client can use reliably without a developer reading the documentation first. The client chooses an operation from its name and description, fills in its parameters, and then reasons over whatever comes back. Building for that client means applying familiar API discipline more strictly: stable and explicit operations, constrained inputs, bounded and paginated responses, structured errors that state whether a retry is safe, and writes that can be repeated safely or confirmed first. Security has to be enforced by the server, because an agent’s instructions cannot be relied on to keep it inside its permissions.
The sections below cover each of those layers in the order you are likely to build them, then explain where the Model Context Protocol (MCP) and API management fit.
What the IETF draft proposes
A useful reference for this design work is the IETF Internet-Draft Design Considerations and Profile for HTTP APIs Consumed by AI Agents, dated June 2026. It is a working draft with an expiry date of 1 January 2027, not a final RFC, so treat its wording as proposed guidance rather than an established standard. The draft sets out when an HTTP API can be described as agent-friendly: An HTTP API meant for agents can be called agent-friendly, in the sense of this document, when:
The properties it lists include stable operation identifiers, cursor pagination, structured retry-aware errors, idempotent writes, and clear marking of untrusted content. Each of these is covered in the sections that follow.
Start with the operation surface
An agent’s most common failure is selection: it calls the wrong operation or none at all. Selection depends on what the model can read, so the names, descriptions, and schemas you publish are part of the interface itself.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
Use stable, intent-revealing identifiers
Give every operation an identifier that states its purpose, such as cancel_order, rather than a generic name like update_resource that forces the model to infer intent from the parameters. Keep identifiers stable across releases. A renamed operation can break any client or prompt that has learned to select it, and the usual symptom is an agent quietly choosing a different operation rather than an obvious error.
Write descriptions that say when not to use the operation
For each operation, document four things: when it should be used, when it should not, what it changes, and what each input and output field means. The “when not to” part matters most when two operations look alike, such as a search that returns candidate records and a delete that acts on them. State the boundary explicitly in both descriptions.
Constrain inputs with strict schemas
Use documented types, fixed value sets for enumerated fields, and length or range limits where they apply. Reject unknown input properties where that is appropriate for the operation. A hallucinated parameter that fails with a clear validation error is far easier to recover from than one that is silently ignored and produces a plausible but wrong result.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallExpose a focused set, not every backend call
Publish the operations an agent needs for its task rather than every endpoint your backend offers. The IETF draft warns that descriptions shape selection and that similarly named tools can shadow one another when several providers share a context. A smaller set of clearly separated operations reduces both risks.
Rank #2
Bound what leaves the server
The model reads every response, so response size costs context window, latency, and money. An unexpectedly large response, whether from a big dataset or a malicious payload, can also do far more damage than a slow one. The controls below keep responses small by default and limit the impact of unexpectedly large or hostile responses.
Enforce size limits on the server
Set maximum page sizes and maximum response sizes in the server itself, not only in the documentation. Return compact data by default, so that a client wanting more must ask for it explicitly.
Use cursor pagination with stable ordering
Return a continuation value with each page and let the client pass it unchanged into the next request. Document the ordering of the collection so that pages neither skip nor repeat records. A typical agent loop looks like this:
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →- Call the list operation with a page size and no cursor.
- Read the continuation value from the response, if one is present.
- Pass that value unchanged into the next call.
- Stop when the response contains no continuation value.
Offer field selection and verbosity controls
Let clients request only the fields they need, for example fields=id,status,updated_at, and offer a compact verbosity setting for list operations. Field selection reduces both the data sent over the wire and the material the model must process, which makes it one of the most direct controls on cost.
Use conditional reads for unchanged data
For resources that agents read repeatedly, support conditional requests so that an unchanged resource returns a short response instead of the full body. In HTTP this is usually done with an ETag validator sent back in an If-None-Match header; the server can then answer 304 Not Modified when nothing has changed.
Make failures and retries legible
A developer can read a stack trace and infer what went wrong. An agent needs fields it can branch on. Return the following in machine-readable form:
- A stable error code for each class of failure, separate from the human-readable message.
- An explicit indication of whether a retry is safe for that failure.
- Rate-limit state and retry delay, so the client does not have to guess when to try again. For example, a Retry-After header on a 429 response.
- Polling guidance for operations that complete asynchronously, including how often to check and when to stop.
Make state-changing requests idempotent
A client that times out on a write cannot tell whether the write succeeded, so it will usually retry. Without protection, that retry can create a second order or a second charge. Accept an idempotency key on each state-changing operation and define two things explicitly: the scope of the key, for example per client and per operation, and how long the server remembers it. Within that window, a repeated request with the same key should return the original outcome rather than repeat the action.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsAdd preview and confirmation for high-impact actions
For writes that are costly or hard to reverse, give the agent a path that shows the effect before it commits. That can be a preview operation that returns what would change, a confirmation step that a user approves, or a cancellation window. Whichever you choose, the server should decide whether the required confirmation was obtained, not the agent.
Choose the integration layer
Four approaches are relevant here. They solve different problems and are not mutually exclusive.
| Option | Problem it solves | Choose it when | What to check |
|---|---|---|---|
| Direct HTTP/API access | Calls the existing API contract without an adapter layer | Your clients reliably use the documented interface | No general rule in the cited documentation says when direct calls outperform an adapter |
| Function tools | Wraps a specialized or proprietary operation with a natural-language description of its purpose, parameters, and return values | One application needs a curated wrapper around particular operations | Selection depends on the quality of the descriptions |
| Model Context Protocol (MCP) | Standard discovery and invocation of tools, prompts, and resources, decoupling agent reasoning from the tool implementation | Several clients or agent frameworks need the same capabilities | Behaviour depends on protocol version and transport, covered below |
| API management | Cataloguing, security, lifecycle governance, and usage monitoring for the underlying APIs | Many APIs need consistent governance across teams | Complements MCP; it does not replace it |
The right layer depends on the size of your API estate, the capabilities of your clients, and your governance requirements. A single internal API used by one application may need only direct access and good descriptions, while a shared estate used by many agents may justify MCP and API management together.
Model Context Protocol: transports and versions
MCP is an open protocol for discovering and invoking tools, prompts, and resources exposed by a server. The OpenAI Agents SDK MCP guide quotes the protocol’s description of itself, MCP is an open protocol that standardizes how applications provide context to LLMs
, and attributes that wording to the official MCP documentation. In Google’s MCP servers overview, local servers use stdio and remote servers use HTTP. The OpenAI Agents SDK documents hosted MCP, Streamable HTTP, HTTP with SSE, and stdio integration paths.
Protocol versions change how sessions work, so check both sides of the connection. As of Google’s MCP documentation in October 2026, its remote MCP servers support MCP version 2026-07-28, which Google describes as a stateless core. In that version each request carries the information needed for routing, and the earlier initialization handshake and Mcp-Session-Id header are not used. Clients or gateways that still assume a session may need changes. Confirm which version your client and server actually negotiate before relying on this behaviour.
Best Value
Limit what the agent can see
When a server has many capabilities, use tool filtering or toolsets to expose only the operations a given agent needs. Google’s Architecture Center guidance on agentic AI components warns that too many tool definitions can increase confusion, latency, and cost.
Where API management fits
API management keeps the underlying APIs governable through cataloguing, authentication, rate limiting, lifecycle governance, and monitoring. Google describes it as complementary to MCP rather than a substitute, so an enterprise can run both: MCP for how agents discover and call tools, and API management for the APIs behind them. The same Architecture Center guidance names Apigee API hub for managing agent API tools at enterprise scale, and Cloud Run as one option for hosting a custom MCP server.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Secure the agent-to-API boundary
Assume the agent can be manipulated. Text from users and third parties can contain instructions aimed at the model, so the controls that matter sit in the API and its identity layer. Google Cloud’s guidance on AI security and safety for MCP servers covers agent modes, identity, least privilege, and prompt injection. The checklist below applies those principles to any agent-facing API.
Quick Recap
- Give the agent its own identity. Grant only the roles and permissions the current task needs, and do not hand the agent a human’s broad credentials.
- Keep credentials out of URLs. Send tokens in an authorization field or header. URLs are routinely written to logs and proxies.
- Enforce authorization at the API. Every operation checks the caller’s permissions. The agent’s prompt is not an access control.
- Separate untrusted text from control fields. Keep user-supplied and third-party text in clearly labelled data fields. Never let that text decide which operation runs or which permissions apply.
- Log the acting identity and the delegation. Record which user authorised which agent to perform which action, and accept a correlation identifier so a request can be traced across services.
- Verify confirmations on the server. A preview or confirmation step protects you only if the server checks that it occurred before executing the write.
Before you ship
- Confirm that every operation has a stable identifier, a when-to-use and when-not-to-use description, and a strict input schema.
- Send a deliberately large request to each list operation and confirm the server caps the response and that the continuation value returns the next page without repeats.
- Check which MCP version your client and server negotiate, and whether any gateway in between assumes a session.
- Replay a timed-out write with its idempotency key and confirm it does not run twice.
- Check the IETF draft’s status before citing its properties as a standard, and recheck current MCP and cloud product documentation before each rollout, because protocol versions and cloud features change.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
