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 makes its intended operations, input constraints, side effects, errors, and continuation rules explicit in machine-readable form. The agent can then select a tool, construct a valid request, interpret the result, and recover from failure without guessing. This is a practical design profile, not a guarantee that every model will succeed.
The key principle is that both the API description and the data it returns become inputs to an agent’s reasoning. Treat the OpenAPI description, response shapes, and runtime behavior as one callable interface rather than as documentation added after implementation.
What makes an API agent-friendly?
An API is agent-friendly when a tool layer can expose it without inventing missing rules. A useful description tells the client what each operation does, when to use it, which parameters are required, what values are allowed, what side effects occur, and what the response fields mean. Runtime responses then preserve those promises with predictable structures.
Four properties matter most:
- Discoverability: operation names and descriptions make similar actions distinguishable.
- Constrained calls: schemas express types, required fields, allowed values, and object boundaries.
- Recoverability: errors identify the problem and indicate whether changing or retrying the request can help.
- Predictable scale and effects: collections are bounded and continuations are ready to use; writes explain and control retries.
The June 2026 IETF Internet-Draft Design Considerations and Profile for HTTP APIs Consumed by AI Agents organizes recommendations around these concerns. It is work in progress, not a finalized RFC, and the cited revision says it expires on 1 January 2027. Use it as guidance and recheck later revisions before treating any draft detail as a requirement.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
Start with the API description as a callable contract
OpenAPI 3.0.3 can be written in YAML or JSON and can be split across connected documents. It describes paths, operations, parameters, request bodies, responses, and schemas. A generated tool converter may support only part of that feature set, so validate the final description against the platform that will invoke it.
Give every operation a distinct, stable identity
Use an operation identifier that combines the resource and intent, such as listInvoices, getInvoice, createInvoice, and cancelInvoice. Avoid vague names such as process or manage. Names should remain stable so prompts, logs, and client code do not change when prose is edited.
The summary and description should answer, in this order:
Recommended Free Tools
- What resource or action is involved?
- When should a caller use this operation?
- When should it not be used, and which similar operation is appropriate instead?
- What side effects, permissions, or irreversible consequences apply?
Put the distinction between similar operations near the beginning. State side effects explicitly; an agent should not have to infer that a POST sends an email, charges an account, or changes a production setting.
Describe parameters as precisely as the server validates them
For every path, query, header, and body property, document its type, requiredness, format, units, default, and realistic example. Explain relationships that a generic schema cannot express, such as “end_date must be on or after start_date.” Keep names consistent across operations: changing from customer_id to clientId without a strong reason increases tool-selection and call-construction errors.
Use constraints wherever the receiving tool layer supports them:
- Use integer minimum and maximum values for bounded counts.
- Use string formats for dates, date-times, UUIDs, and email addresses when those formats are actually enforced.
- Mark required properties explicitly instead of relying on prose.
- Use an
enumfor a genuinely closed set of values when the target platform supports it. - Reject unknown object members with
additionalProperties: false, or an equivalent closed-object constraint, where extension fields are not intended.
Do not put constraints in the description that the server does not enforce. If a value is only advisory, label it as such rather than presenting it as a validation rule.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Use examples that expose realistic decisions
Examples should show the smallest valid request and one realistic response. Include boundary cases that affect tool choice, such as an empty filter, a maximum page size, or a status transition that is not allowed. An example should never contradict the schema or omit a field that the response contract says is always present.
Rank #2
Make response fields understandable
Describe response properties, not just request inputs. Explain whether an identifier is stable, whether a timestamp is UTC, whether a field can be null, and whether an array is ordered. If a field is a cursor, say that it is opaque and must be sent back unchanged. If a value is an estimate, label it as an estimate.
Schema constraints must match the tool platform
JSON Schema’s enum restricts a value to a fixed set. That is generally useful for statuses, sort directions, and other closed domains, but support varies by tool runtime.
Bedrock action groups are a specific compatibility caveat
Amazon Bedrock’s agent action-group documentation describes OpenAPI schemas as the source for operations and required parameters, while supporting only a subset of OpenAPI 3.0. Its documentation says the enum field is unsupported for restricting parameter values and recommends listing allowed values in the parameter description instead. That is a Bedrock-specific workaround, not a reason to remove validation from APIs or schemas used by other platforms.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →For a Bedrock-targeted definition, write a description such as “sort accepts only created_at or updated_at; default is created_at,” and enforce the same set on the server. Keep a compatibility test for the exact action-group converter because supported features can change.
Test the converted tool, not only the source document
After generating tools, inspect the exposed names, parameter types, required flags, descriptions, and response handling. A valid OpenAPI document can still lose information during conversion. Compare the generated interface with the source and exercise:
- A minimal valid call.
- A call that omits each required field.
- Each allowed value and one disallowed value.
- An unknown property.
- An empty result and a multi-page result.
Return structured errors that support recovery
HTTP status codes tell a caller the broad class of failure, but an agent often needs to know what to change and whether a retry is sensible. RFC 9457 defines the application/problem+json media type for problem details and supersedes RFC 7807.
Use the RFC 9457 problem-details shape
A problem response can include standard members such as type, title, status, detail, and instance. The type should identify a stable problem kind, preferably with a durable URI under your control. Extensions can carry application-specific fields.
{"type":"https://api.example.com/problems/invalid-parameter","title":"Invalid parameter","status":400,"detail":"The requested date range is invalid.","code":"invalid_parameter","retryable":false,"errors":[{"field":"end_date","reason":"must be on or after start_date"}]}Problem details are not mandatory for every response. If the response is still a normal resource representation, the application’s resource format may be clearer. A status code alone can be sufficient when no additional explanation is useful.
Add stable, machine-readable recovery information
The IETF agent-focused draft recommends making recovery properties explicit. These are draft recommendations and extension examples, not fields registered by RFC 9457:
code: a stable application error identifier that does not change with wording.retryable: whether repeating the same request may succeed.retry_afteror a similar delay hint: how long to wait when a retry is appropriate.errors: field-level validation failures, including the field path and reason.
A rate-limit response can be retryable after a delay. Invalid input normally is not: the client must change the request rather than repeat it unchanged. Authentication failures may require refreshing credentials, while authorization failures generally require a different identity or permission. Make those distinctions visible instead of forcing the agent to infer them from prose.
Keep validation errors actionable
Return one entry per invalid field when possible. Use a consistent field-path notation for nested properties, such as line_items[2].quantity. Include the accepted range or values when revealing them is safe. Do not return an HTML error page, a stack trace, or a single opaque sentence when the caller can correct a specific field.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated 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 matchKeep error semantics stable across versions
Do not reuse one error code for unrelated conditions. Preserve the meaning of a code even if the human-readable title changes. Version or deprecate codes deliberately, and document whether unknown extension members should be ignored. Log a correlation identifier, but do not require an agent to parse logs to understand the correction.
Bound collections and make pagination continuation automatic
Unbounded or very large default collections can crowd the model’s context with low-value records. The agent-focused draft recommends a bounded default page size, a documented way to narrow results, stable ordering, cursor-based pagination, and a ready-to-use continuation value.
Choose a safe default and an enforced maximum
Set a default that is small enough for normal tool output and a maximum that protects the service. Document both values and reject or clamp an oversized request consistently. If the caller asks for more than the maximum, return the effective limit in the response so it knows why fewer records arrived.
Prefer opaque cursors to calculated offsets
Offset pagination becomes unstable when records are inserted or deleted between requests and encourages clients to guess the next URL. A cursor can encode the server’s position and filtering context without exposing implementation details. Treat it as opaque: clients should send it back exactly as returned.
Free tools Windows power users keep installed
One-click scans. No signup required.
{"items":[{"id":"inv_1042","created_at":"2026-10-15T12:00:00Z"}],"page":{"limit":25,"next_cursor":"eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0xNVQxMjowMDowMFoifQ","has_more":true}}Alternatively, return a complete next link containing the cursor and all required filters. A complete link is easier for an agent to call than instructions to reconstruct a URL from separate pieces.
Guarantee stable ordering
Order by a deterministic key, commonly a timestamp plus a unique identifier as a tie-breaker. Document the default order and supported sort fields. Keep the filter and sort context bound to the cursor, or reject a cursor used with incompatible parameters. If a consistent snapshot is not guaranteed, state that records may appear or disappear between pages.
Handle empty and terminal pages clearly
Return an empty array for no matches, not a different response shape. On the last page, use a consistent signal such as has_more: false and a null or absent cursor. Do not return a cursor that loops back to an earlier page. Test repeated calls with the same cursor to ensure the behavior is documented and safe.
Make writes safe to retry
Reads are usually repeatable; writes can create duplicate orders, messages, charges, or jobs when a network timeout occurs after the server has committed the change. The caller cannot know whether it is safe to send the request again unless the API defines retry behavior.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsDocument side effects before the call is made
Mark operations that create, modify, publish, delete, notify, charge, or trigger asynchronous work. Explain permission requirements, irreversible consequences, and any asynchronous job that the caller must poll. Do not imply safety from the HTTP verb alone: a PUT may still trigger downstream effects, and a POST may be intentionally idempotent when the API defines it that way.
Use idempotency keys for side-effecting operations
For a write that may be retried, accept a client-supplied idempotency key, usually in a header. Document its scope, retention period, and what happens if the same key is reused with a different payload. A retry with the same key should return the original outcome or a clearly defined equivalent without repeating the side effect.
Expose idempotency support in the operation description and response documentation. State whether keys are required or optional, how long they remain valid, and which status codes are safe to retry. A timeout is not proof that the operation failed; the recovery path should be “retry with the same key,” not “send a new request.”
Preview or confirm high-risk actions
For actions with financial, legal, security, or irreversible impact, consider a dry-run preview that returns the planned changes and required confirmations. A separate confirmation step or explicit confirmation token can prevent an agent from turning an ambiguous instruction into an immediate destructive action. These are design patterns to evaluate against the operation’s consequences, not mandatory requirements for every write.
Make asynchronous writes observable
If a write queues work, return a stable job identifier and a documented status operation. Define states such as queued, running, succeeded, and failed, and use the same structured error model for terminal failure. Tell the caller whether polling is safe, how often to poll, and when a job expires.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Evaluate an API with a practical agent-friendliness checklist
The following axes are useful when reviewing an existing API. They are practical comparison dimensions, not a published scoring system.
| Axis | What to inspect | Warning signs |
|---|---|---|
| Schema clarity | Types, required fields, allowed values, formats, examples, response fields, and object boundaries are explicit. | Rules exist only in prose; nullability and requiredness vary between endpoints. |
| Tool compatibility | The target converter supports the OpenAPI features used, and generated tools preserve constraints. | Enums, unions, callbacks, or references disappear during conversion without a compatibility test. |
| Operation discoverability | Stable identifiers and distinct descriptions explain intent, alternatives, and side effects. | Several operations have vague names or nearly identical summaries. |
| Error recoverability | Problem details include stable codes, field-level causes, and explicit retry guidance. | The client must parse prose, guess retry behavior, or inspect server logs. |
| Pagination predictability | Defaults and maxima are bounded; ordering is stable; a cursor or complete next link is returned. | Clients calculate offsets, reconstruct URLs, or receive unbounded arrays. |
| Write safety | Side effects are documented, idempotency is available where appropriate, and risky actions can be previewed or confirmed. | Timeout recovery can duplicate an effect, or the only safety advice is “try again.” |
A build-and-test workflow
- Inventory operations. List every callable action, its resource, side effect, permissions, and likely alternatives.
- Write the OpenAPI contract. Add stable operation identifiers, concise intent-first descriptions, complete request and response schemas, required flags, constraints, and examples.
- Close the input surface. Add
additionalProperties: falseor an equivalent rule where unknown fields should be rejected, and confirm that this matches your extension policy. - Map platform support. Run the exact document through the target tool converter. Record unsupported features and apply platform-specific workarounds only where needed.
- Standardize failures. Select problem types and stable codes; add retryability, delay hints, and field-level errors where they improve recovery.
- Bound every collection. Set defaults and maxima, define deterministic ordering, implement opaque cursors, and return a next cursor or complete link.
- Protect writes. Add idempotency keys to retry-sensitive operations and decide whether preview or confirmation is appropriate.
- Test recovery paths. Simulate validation errors, expired credentials, rate limits, timeouts after commit, duplicate keys, empty pages, and concurrent updates. Verify that the response tells a client what to do next.
- Monitor contract drift. Compare the deployed behavior with the published schema and run converter tests whenever the platform or API description changes.
Common failure modes and fixes
The agent chooses the wrong operation
Usually the operations are too similarly named or their descriptions omit the distinction. Rename them around resource and intent, put the decision rule first, and explicitly say when an operation must not be used.
The agent sends invented fields
Close request objects where appropriate, mark required properties, and reject unknown members with a structured validation problem. If extensions are allowed, define their namespace and shape instead of accepting arbitrary keys.
The agent repeats an invalid request
Return a stable code, a non-retryable indication, and field-level corrections. Reserve retryable guidance for conditions where repeating after a change or delay can plausibly succeed.
The agent stops after the first page
Return a ready-to-use cursor or complete next link, explain that more results exist, and keep the collection shape identical on every page. Do not require offset arithmetic or URL construction.
A timeout creates a duplicate side effect
Require or strongly encourage idempotency keys for the operation, document their retention and payload matching rules, and tell the client to retry with the same key after an uncertain outcome.
A schema works in one tool layer but not another
OpenAPI is a contract format, not a promise that every converter implements every feature. Maintain a support matrix and test the generated interface. For example, the documented lack of enum support in Bedrock action groups requires a description-level explanation plus server-side validation.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
What the evidence does—and does not—show
The agent-focused IETF material provides design recommendations, not a measured success-rate comparison. It specifically notes that the effect of operation naming can vary by model. The primary sources reviewed do not establish a quantified improvement attributable to any one schema, error, pagination, or idempotency practice, so an API team should measure its own tool calls, correction rates, retries, and task completion under controlled tests rather than promise a universal percentage.
The strongest defensible claim is operational: explicit contracts reduce ambiguity for the tool layer, while bounded outputs and structured recovery give clients fewer details to infer. Whether a particular model uses those signals correctly still depends on the model, the converter, the prompt, and the surrounding application.
Bottom line for API designers
Design the description and runtime behavior together. Name operations by resource and intent, encode constraints that the target platform actually supports, describe response fields, return RFC 9457-compatible problem details with clear recovery extensions, bound and cursor collections, and make side-effecting writes idempotent or confirmable. Treat the June 2026 IETF profile as evolving guidance, validate the generated tools on your chosen platform, and test uncertain, invalid, paginated, and retried calls—not just the happy path.
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.
Free tools Windows power users keep installed
One-click scans. No signup required.
