An agent-friendly API is one an AI client can use without a person correcting each step. It selects the right operation from the description, sends arguments that match a strict schema, reads results that stay small, and knows whether a failed call can be retried safely. Scaling that design means adding server-enforced limits on response size, cursor pagination, and idempotent writes. Start from the API’s existing contract, then add MCP or API management where discovery, interoperability, or governance require them. Neither replaces sound API engineering.
What “agent-friendly” means, and how much weight to give the draft
The most specific public description is the IETF Internet-Draft Design Considerations and Profile for HTTP APIs Consumed by AI Agents, dated June 2026. It defines agent-friendliness through properties rather than a single protocol, opening with the sentence “An HTTP API meant for agents can be called agent-friendly, in the sense of this document, when:” The document is an Internet-Draft with an expiry date of 1 January 2027, not a finished RFC. Treat its properties as a proposed design checklist that may change in later revisions.
As an Amazon Associate I earn from qualifying purchases.
| Property | What it means for the API | Failure it prevents |
|---|---|---|
| Stable operation identifiers | Same name and meaning across releases; a changed meaning gets a new identifier | The agent picks the wrong operation after a rename or semantic change |
| Constrained inputs | Documented types, fixed value sets, and rejection of unknown properties where suitable | Malformed arguments are silently misread |
| Bounded outputs | Server-enforced page and response limits; compact defaults | Context overflow, slow responses, and unexpected cost |
| Cursor pagination | A continuation value passed unchanged to the next request; documented stable ordering | Duplicated or skipped records across pages |
| Structured, retry-aware errors | A stable error code plus an explicit retry indication | Blind retries of failures that will never succeed |
| Idempotent writes | Documented idempotency scope and retention period | Duplicate records or repeated side effects after a timeout |
| Marked untrusted content | Third-party or user text labeled as data, separate from control fields | Instructions hidden in returned content being treated as commands |
Each row addresses a failure that appears when a machine rather than a developer is the caller. A developer reads a changelog and notices a renamed field. An agent simply chooses a different operation or passes a value it cannot interpret.
Free tools Windows power users keep installed
One-click scans. No signup required.
Design operations so agents select the right one
Tool selection is driven by text. The agent decides from the name, description, and parameter definitions, so those belong to the contract rather than to documentation written afterward. The IETF draft notes that descriptions affect selection and that similarly named tools can shadow one another when several providers share one context.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
For each operation, document:
- A stable, intent-revealing identifier such as
cancel_subscriptionrather thanop_17. Keep it unchanged across releases. - When to use the operation and when not to. The “do not use” clause prevents the most common misselection: two operations that look alike, such as
search_ordersandget_order. - Its side effects: whether it reads, creates, updates, deletes, or sends something outside the system.
- The meaning of each input and output field, including units, time zones, and what an empty result means.
Constrain inputs with strict schemas: documented types, fixed value sets for status or currency codes, and rejection of unknown properties where that suits the API. A rejected call with a precise message is safer than one that silently ignores a misspelled field such as amout. Expose a focused set of operations rather than every backend endpoint, because each extra definition competes with the others during selection.
Bound what goes in and what comes back
Unbounded responses are the most common way an agent-facing API degrades. A list endpoint that returns thousands of records consumes the model’s context window, adds latency, and raises cost. A malicious or malformed response can do the same at scale. Bounding is a server responsibility: a client that asks for a page size of 10,000 should receive the server’s maximum, not the request.
Cursor pagination and stable ordering
Use cursor pagination. Each response returns a continuation value that the client passes unchanged to the next request, and the collection has a documented, stable sort order. Offset pagination is fragile when records are inserted or removed between pages. An agent that re-requests a page after an error can then see duplicates or gaps. An illustrative response shape:
Rank #2
{"items": [ ... 50 records ... ], "next_cursor": "eyJpZCI6MTIzfQ"}Compact by default, field selection on request
Return a compact representation by default and offer field selection, for example fields=id,status,updated_at, or a verbosity parameter for callers that need more. Set defaults small enough that an unconfigured agent call is safe to make.
Conditional reads
The IETF draft describes conditional reads as a way to avoid retransmitting unchanged data. The mechanism is standard HTTP: an ETag returned with a response, and an If-None-Match header on the next read, which lets the server answer “not modified” instead of resending the body.
Make errors and retries machine-readable
An agent decides whether to retry by reading the response, not by judging the situation. Every error should carry a stable code, a readable message that can appear in the transcript, and an explicit statement of whether retrying is safe. An illustrative error body:
{"error": {"code": "RATE_LIMITED", "message": "Request quota exceeded for this client.", "retryable": true, "retry_after_seconds": 30}}Rate limits and polling
State rate limits and polling intervals in machine-readable form. Send the standard Retry-After header on throttled responses. For long-running jobs, document how long completion typically takes so an agent does not poll every second for a process that needs ten minutes. Give the minimum wait, not a vague “try again later.”
Idempotency for writes
A write that times out is the dangerous case. The agent cannot tell whether the action happened, so it will probably try again. Require an idempotency key on state-changing operations. The server stores the outcome for a documented scope and duration, and a repeated request with the same key returns the stored result instead of repeating the action. Document three things: what the key is scoped to (a client, an account, or an operation), how long results are kept, and what happens when the same key arrives with a different payload. That case should be rejected. Where a key is impractical, equivalent semantics can work, such as a client-assigned resource identifier that makes a create-or-update naturally repeatable.
Choose the integration layer by the problem it solves
Four options come up in practice. They are not mutually exclusive. An enterprise might expose its REST API directly to internal services, wrap a few operations as function tools, publish a curated MCP server for agent applications, and govern all of it through API management. Google’s architecture guidance describes the same range of tool patterns in its Choose your agentic AI architecture components guide.
| Option | Problem it solves | Trade-offs to check |
|---|---|---|
| Direct HTTP/API access | Keeps the existing API contract; the simplest path when clients can reliably use the documented interface | Clients must handle the API’s own authentication, pagination, and error conventions. No single source establishes when direct calls outperform an adapter, so validate this with your own clients. |
| Function tools | Wraps specialized or proprietary operations with natural-language descriptions of purpose, parameters, and return values | Tools are defined inside the application that uses them, so reuse across other clients takes additional work. |
| MCP | A standard way for an agent application to discover and invoke tools, prompts, and resources from a server, separating agent reasoning from a specific tool implementation | Client and server must agree on protocol version and transport, and the exposed tool list still needs curation. |
| API management | Catalogs APIs and centralizes security, lifecycle governance, and usage monitoring | It adds a platform to operate. It does not make an operation easier for an agent to select, so the design rules above still apply. |
When comparing options, evaluate interoperability, discoverability, tool selection, access control, observability, operational ownership, deployment constraints, and compatibility with existing clients. The right layer depends on the API estate, the client capabilities, and the governance requirements, so avoid a rule that one layer is always best.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.MCP: what to verify before building on it
MCP is an open protocol. The OpenAI Agents SDK documentation quotes the official description: “MCP is an open protocol that standardizes how applications provide context to LLMs.” The same page covers hosted MCP, Streamable HTTP, HTTP with SSE, and stdio integration paths, along with guidance on caching, pagination, tracing, and security. See the OpenAI Agents SDK MCP guide.
Transport and protocol version
Google’s MCP servers overview describes local servers that use stdio and remote servers that use HTTP. As of Google’s documentation checked on 8 October 2026, its remote MCP servers support protocol version 2026-07-28. Google describes that version as a stateless core: each request carries the information needed for routing, with no initialization handshake and no Mcp-Session-Id. Treat this as version-specific behavior and confirm that both client and server support it before relying on it. If you run several instances behind a load balancer, the absence of session identifiers means no single session has to stay pinned to one instance. Verify that in your own deployment.
Keep the tool surface small
Use tool filtering or toolsets to expose only the operations a given agent needs. Google warns that too many tool definitions can increase confusion, latency, and cost. That is the selection problem from earlier, in a different form. A server that exposes every endpoint to an agent that needs six operations invites misselection.
Where API management and hosting fit
Google’s architecture guidance treats API management as complementary to MCP rather than a substitute. For enterprises that need cataloging, access policies, and usage monitoring across many agent tools, it names Apigee API hub. For hosting a custom MCP server, it names Cloud Run as one option. These are examples rather than requirements. Choose a gateway or hosting platform that provides the controls your governance model needs.
Security: enforce at the API, not in the prompt
Google’s AI security and safety guidance for MCP servers covers agent modes, identity, least privilege, and prompt injection. It points to the same principle as the IETF draft: the control belongs where the request is executed. In practice:
Windows 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 reinstallOutdated 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 match- Give each agent its own identity. Grant only the roles and scopes the task requires, and review them when the task changes.
- Enforce authorization in the API. A system prompt that says “do not delete records” is not an access control. The server must refuse the operation for any caller without the permission.
- Keep credentials out of URLs. Send tokens in the Authorization header. URLs end up in logs, proxies, and browser history.
- Label untrusted text. Content from users and third parties, such as emails, tickets, web pages, and document bodies, should be returned in fields marked as data and kept separate from trusted control fields. This limits prompt injection through returned content but does not eliminate it.
- Audit delegated actions. Log both the agent identity and the user it acts for. Accept a correlation identifier so one user request can be traced across several calls.
- Require confirmation for high-impact writes. Offer a preview or dry-run path, and require explicit user approval before actions that cannot be undone.
Troubleshooting: symptoms and where to look first
| Symptom | First check |
|---|---|
| The agent calls the wrong operation | Compare the descriptions of the overlapping operations, including their “do not use” clauses, and check whether another connected server exposes a similarly named tool. |
| The agent retries a failed call repeatedly | Confirm that error responses include a retryable flag and a retry delay. Without them, the agent has to guess. |
| Duplicate records after a timeout | Confirm that the write accepts an idempotency key and that the key’s scope matches the retry path. |
| Context fills quickly or responses are slow | Check the server-side maximums, the default field set, and whether list endpoints return full records. |
| Pages repeat or skip records | Check that the sort order is stable and that the cursor is passed back unchanged. |
| An MCP session fails to start | Confirm that client and server use the same protocol version and transport, and remember that the 2026-07-28 version does not use session identifiers. |
What the sources establish and what they leave open
The sources behind this article include no published performance, adoption, or cost figures, so this article makes no benchmark claim. The guidance here is design guidance. It is consistent across the IETF draft, the OpenAI Agents SDK documentation, and Google’s MCP and architecture pages, but it has not been tested against a specific production workload. Before deciding how far to take any of these properties, measure response sizes, retry rates, and operation misselection in your own traffic.
Repeated checks of the MCP and cloud-product details are worthwhile, since protocol versions and product features change. The version-specific statements in this article reflect Google’s documentation as checked in October 2026.
Quick Recap
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.
