Recommended Free Tools
An API is agent-friendly when an AI tool layer can discover the right operation, construct a valid request, understand the response, and recover safely when something goes wrong. That requires more than exposing HTTP endpoints: operation names and descriptions must communicate intent, schemas must make constraints explicit, errors must distinguish correction from retry, collection responses must have bounded and predictable continuation, and side-effecting writes must be safe to repeat.
This is a practical design profile, not a guarantee that every model will succeed. The current agent-specific guidance is an Internet-Draft published in June 2026, marked work in progress and set to expire on 1 January 2027. Treat its recommendations as implementation guidance alongside the finalized OpenAPI Specification 3.0.3 and RFC 9457.
As an Amazon Associate I earn from qualifying purchases.
What makes an API agent-friendly?
Agent-friendly design makes the intended operation and its constraints explicit in machine-readable form, then keeps runtime behavior predictable. An agent typically sees an API description before it calls anything and receives response data after each call. As Nishant Gaikwad writes in the IETF draft Design Considerations and Profile for HTTP APIs Consumed by AI Agents, “The description of the API, and the data the API returns, both become input to the agent’s own reasoning.”
Free tools Windows power users keep installed
One-click scans. No signup required.
That framing changes the design target. A human developer may infer that two similarly named endpoints have different side effects, know that a date is required from surrounding documentation, or inspect a stack trace to find the bad field. A tool-calling model needs those distinctions exposed where its tool selector and argument generator can use them.
#1 Best Overall
- API Design Patterns
- ABIS BOOK
- Manning Publications
- Discoverability: stable operation identifiers and distinct descriptions help the agent select the intended action.
- Constraint visibility: types, required fields, allowed values, limits, and response shapes prevent avoidable invalid calls.
- Recovery: structured errors tell the client what happened, whether waiting may help, and which input needs changing.
- Bounded output: predictable page sizes and ready-to-use cursors prevent a collection from overwhelming the context window.
- Write safety: explicit side effects, idempotency, and optional preview or confirmation flows reduce accidental duplication and irreversible actions.
These practices improve the interface available to an agent; they do not establish a measured success-rate increase. The reviewed primary material does not provide a directly usable quantitative comparison between alternative designs, and the draft notes that the effect of operation naming varies by model.
Make the API description a callable contract
An OpenAPI description can be represented as JSON or YAML and can consist of one document or multiple connected parts. It describes schemas and operations, but an implementation or tool converter may support only a subset of the specification. Design the description as the contract a generated tool layer will actually consume, then verify it against the target platform.
Name operations for intent, not implementation history
Use a stable identifier that makes the resource and action distinguishable without opening source code. Names such as listInvoices, getInvoice, createInvoice, and voidInvoice communicate different intents. Avoid overloaded names such as manageInvoice or identifiers that differ only by an internal version suffix.
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 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteKeep a name stable when the operation’s meaning remains stable. Renaming a tool can affect prompts, cached tool selections, audit rules, and client code even when the HTTP route has not changed.
Put the decision-critical description first
Each operation summary should state what it does in plain language. Its longer description should explain when to use it, when not to use it, the resource it changes or returns, and any consequential side effect. Put the most important constraint early rather than burying it after implementation notes.
For example, a useful description distinguishes “Creates a draft invoice without sending it” from “Creates and sends an invoice to the customer.” It should say whether the call charges a payment method, sends a notification, publishes data, or only prepares a draft. Do not expect the agent to infer side effects from POST, PUT, or DELETE.
Describe every parameter and response field
For request parameters, specify the type, requiredness, format, units, allowed values, default behavior, and relationships with other fields. State whether a value is inclusive or exclusive at a boundary, whether an identifier is case-sensitive, and which time zone applies to a timestamp.
Response schemas deserve the same care. Explain identifiers, status values, nullable fields, monetary units, timestamp semantics, and whether a field can be absent. An agent cannot reliably use a response field whose meaning exists only in prose outside the description.
Constrain objects against invented arguments
Where suitable, set additionalProperties to false, or use an equivalent constraint supported by the receiving tool layer. This reduces the chance that a model invents a parameter that your server silently ignores or mishandles. Apply the rule deliberately: extension points, metadata maps, and forward-compatible objects may need additional properties, while command objects with a closed set of fields usually benefit from strictness.
Rank #2
Use realistic examples as disambiguation
Examples should show valid combinations, not merely syntactically correct values. Include the smallest useful request and a representative response. If a field accepts an ISO date, show the format. If a filter is mutually exclusive with another filter, show one valid branch and explain the restriction. Examples do not replace schemas, but they give the model concrete patterns to imitate.
Build a tool schema step by step
- Inventory operations. List each externally callable action, its resource, read or write behavior, and whether it can trigger an external side effect.
- Separate similar intents. Split actions that differ in lifecycle state, audience, or consequence. A preview, create, send, and cancel operation should not be collapsed into one ambiguous command.
- Define input objects. Mark required fields, formats, bounds, enumerations where supported, mutually exclusive fields, and defaults. Reject unknown fields when the object is intentionally closed.
- Define output objects. Document response fields, nullability, pagination metadata, and stable identifiers. Give the continuation mechanism its own schema.
- Write the operation text. State what happens, when to use the operation, when not to use it, and whether it changes external state.
- Add valid examples. Include realistic values and at least one response containing the fields an agent must use in its next step.
- Validate against the target tool platform. A specification-valid feature may still be unsupported by a converter or action-group runtime. Test generated tools, not only the source document.
Schema compatibility is a platform constraint
JSON Schema’s enum restricts a value to a fixed set. That is generally useful validation: a status field can accept only documented states, and the server can reject anything else. However, Amazon Bedrock’s agent action-group documentation says its OpenAPI support covers only a subset of OpenAPI 3.0 and does not support the OpenAPI enum field for restricting parameter values. Its documented workaround is to describe the allowed values in the parameter description.
That is a Bedrock-specific compatibility workaround, not a reason to remove validation from every API. Keep the canonical schema precise, then adapt or generate a platform-specific projection when the receiving tool layer lacks a feature. If you describe an allowed-value workaround, enforce the values on the server as well; descriptive text alone is not validation.
| Design choice | General API practice | When the target platform differs |
|---|---|---|
| Fixed allowed values | Use a schema constraint such as enum and validate server-side. |
Check the converter’s supported subset; if enum is unsupported, document the values and retain server-side rejection. |
| Unknown object fields | Set additionalProperties to false for closed command objects where appropriate. |
Confirm that the tool layer preserves the constraint; otherwise reject unknown fields at the API boundary. |
| Multiple documents | Use connected OpenAPI parts when that fits your governance and deployment model. | Confirm that the importer resolves references and exposes all intended operations. |
Return errors that support recovery
RFC 9457 standardizes problem details for HTTP errors with the media type application/problem+json. The type member identifies the problem kind; standard members include a human-readable title, a detail message, and the HTTP status context. Extension members can carry application-specific structured information.
Problem details are not mandatory for every response. If the response is still a normal resource representation, the application’s own representation may be more appropriate. If no additional explanation is useful, an HTTP status code can be sufficient. Use problem details when the client needs structured information to decide what to do next.
Separate retryable failures from request defects
An agent needs to know whether repeating the same request makes sense. A temporary rate limit may become successful after a delay; an invalid date or unauthorized operation normally requires a different request or authorization context. The June 2026 IETF draft recommends exposing a stable error code and machine-readable retry guidance, such as a retryable flag, an optional delay hint, and field-specific validation details. These are draft recommendations or examples, not registered RFC 9457 fields.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →A useful application extension can look like this:
{
"type": "https://api.example.invalid/problems/validation-error",
"title": "Request validation failed",
"status": 422,
"detail": "Two fields need correction.",
"code": "validation_failed",
"retryable": false,
"errors": [
{"field": "currency", "code": "unsupported_value", "allowed": ["USD", "EUR"]},
{"field": "amount", "code": "must_be_positive"}
]
}The URI in this illustrative payload is a documentation identifier, not a recommendation to copy it into a production API. In a real service, use a stable problem type that your organization owns and documents.
Give validation errors field-level precision
Return a machine-readable location for each invalid value, a stable reason code, and enough context to form a corrected request. For nested arrays, identify the item path rather than returning only “invalid request.” Include allowed values or bounds when they are safe to disclose. Do not make the model parse a concatenated log line to discover which field failed.
Make transient failures actionable
For a retryable response, provide a delay hint when the server can calculate one and honor standard HTTP rate-limit conventions used by your clients. Make clear whether the delay is in seconds, an absolute time, or merely advisory. For a non-retryable authorization or validation error, explain what must change instead of inviting an immediate retry.
Keep error contracts stable
Do not change a problem code’s meaning between deployments. Add fields compatibly, document whether fields are optional, and preserve the HTTP status and type semantics for existing clients. Log a server-side correlation identifier and return it in the problem details when operators need to trace a failed tool call; do not put secrets or sensitive request data into the error.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Bound collection responses and make continuation easy
Unbounded lists can crowd useful information out of an agent’s context and make latency unpredictable. Set a bounded default page size, document how callers can request a smaller page, and enforce a maximum even when a client asks for more.
Prefer cursors for changing collections
Cursor-based pagination lets the server encode a position that remains meaningful as records are inserted or removed. Return a ready-to-use cursor or a complete next-page link so the agent can continue without calculating offsets or constructing URLs. Treat cursors as opaque: clients should send them back unchanged rather than decode or modify them.
Keep ordering stable
Define an explicit sort order and a deterministic tie-breaker, such as a unique identifier after a timestamp. A stable order prevents records from moving between pages while the agent is traversing a collection. Document what happens when an item is deleted or updated during traversal and how long a cursor remains valid.
Design the response for the next call
A collection response should identify the items, the applied limit, and whether another page exists. The continuation value should be easy to find and valid for the same operation. For example:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
{
"items": [
{"id": "inv_1042", "status": "open", "created_at": "2026-10-12T09:30:00Z"}
],
"page": {
"limit": 25,
"next_cursor": "opaque-cursor-value",
"has_more": true
}
}This shape is illustrative. Choose field names that are consistent across your API and describe whether an absent cursor, a null cursor, or an empty string means that traversal is complete.
Prevent pagination failure loops
- Reject malformed or expired cursors with a structured, non-retryable error that tells the client to restart from the first page.
- Do not return the same cursor indefinitely; detect server-side cursor bugs and alert on repeated tokens.
- Keep the maximum page size bounded even for trusted clients unless a separate bulk-export path exists.
- When filtering or sorting changes, require a new traversal rather than silently reusing a cursor from a different query.
Make side-effecting writes safe
Writes deserve stronger contracts because an agent may retry after a timeout without knowing whether the first request reached the server. For operations that create, charge, publish, delete, or otherwise change external state, document the side effect and support a client-supplied idempotency key when repeating the same logical request must not repeat its effect.
Define idempotency behavior precisely
State which operations accept the key, where the key is sent, how long the server retains it, and what happens when the same key is reused with different request parameters. A robust contract returns the original result for a matching repeat and rejects a conflicting payload instead of silently performing a second action. Make idempotency support visible in the operation description so the tool layer can include it when appropriate.
Use preview and confirmation for high-risk actions
A dry-run or preview operation can calculate the intended changes without applying them. A confirmation step can require an explicit token or confirmation metadata before an irreversible action. These patterns are not mandatory for every write; evaluate them against the operation’s consequences, reversibility, authorization model, and user expectations. A low-risk draft update may not need the same ceremony as a deletion or financial transfer.
Describe partial success and asynchronous work
If a write queues background work, return a stable operation identifier and describe how to retrieve its status. If a batch can partially succeed, return per-item results and explain whether retrying the entire batch is safe. Do not force an agent to infer completion from a generic 202 response or a human-oriented message.
Evaluate an existing API with a practical scorecard
Use these comparison axes when reviewing an API or choosing between alternative designs. They are practical dimensions, not a published scoring system.
| Axis | Questions to ask | Evidence of a strong design |
|---|---|---|
| Schema clarity | Are types, required fields, allowed values, limits, and response fields explicit? | The generated tool exposes constrained inputs and a documented output shape. |
| Tool compatibility | Does the target agent platform support the OpenAPI features used? | Imports are tested on the actual platform, with a documented compatibility projection where needed. |
| Operation discoverability | Can an agent distinguish similar operations and their side effects? | Names are stable, descriptions are distinct, and read/write consequences are stated. |
| Error recoverability | Can a client identify what happened and what to change? | Problem details include stable types or codes, field paths, and explicit retry guidance where applicable. |
| Pagination predictability | Are page sizes bounded, ordering stable, and continuations ready to use? | The response returns an opaque cursor or next-page link and documents cursor lifetime. |
| Write safety | Are side effects documented and retries idempotent where appropriate? | Idempotency keys, conflict behavior, and preview or confirmation flows are described. |
Common failure modes and fixes
The model chooses the wrong operation
Likely cause: names or descriptions overlap, or side effects are implicit.
Fix: split distinct intents, name the resource and action, state when not to use each operation, and put the consequence in the first sentence.
The model sends plausible but invalid arguments
Likely cause: requiredness, formats, allowed values, or object closure are missing from the schema.
Fix: mark required fields, add formats and bounds, constrain closed objects, include a realistic valid example, and enforce the same rules server-side.
A platform drops a schema constraint
Likely cause: the tool converter supports only a subset of OpenAPI.
Fix: inspect the generated tool definition, maintain a platform compatibility matrix, and provide a documented projection. For the Bedrock action-group limitation on enum, describe allowed values in the parameter text while retaining server validation.
The agent retries an error forever
Likely cause: all failures look alike, with no stable code or retry signal.
Fix: distinguish temporary failures from invalid input, expose draft-style retry guidance such as retryable and a delay hint, and return field-level corrections for validation errors.
The agent cannot finish a list traversal
Likely cause: an unbounded default, unstable ordering, calculated offsets, or an unusable continuation token.
Fix: cap the default and maximum page sizes, define deterministic ordering, return an opaque cursor or complete next-page link, and test cursor expiry and repeated-token behavior.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Scan for outdated or missing drivers - takes under a minute3Clear out junk files and repair common Windows errorsA timeout duplicates a write
Likely cause: the operation has side effects but no idempotency contract.
Fix: accept an idempotency key, persist the key-to-result association for a documented period, reject conflicting reuse, and expose the behavior in the operation description.
An implementation checklist
- Every operation has a stable, intent-specific identifier.
- The summary and description state purpose, usage boundaries, and side effects.
- Request and response schemas document types, requiredness, formats, allowed values, defaults, and realistic examples.
- Closed command objects reject unknown properties where appropriate.
- The canonical OpenAPI document is tested against the actual agent platform or converter.
- Errors use RFC 9457 problem details when structured recovery information is needed.
- Error responses provide stable problem types or application codes and identify fields that need correction.
- Retry guidance distinguishes temporary failures from requests that must change.
- Collection defaults and maxima are bounded, ordering is stable, and continuation is returned ready to use.
- Side-effecting writes document idempotency keys and conflict behavior.
- High-risk actions have an evaluated preview or confirmation pattern.
- Automated contract tests cover generated tool schemas, malformed inputs, expired cursors, retries, and duplicate writes.
What this guidance does—and does not—prove
The June 2026 IETF profile is useful agent-specific guidance, but it is an Internet-Draft rather than a finalized RFC. Internet-Drafts may be updated, replaced, or obsoleted; this revision is marked to expire on 1 January 2027. Recheck the current draft before treating a recommendation as settled protocol policy.
OpenAPI 3.0.3 defines the description format, and RFC 9457 is the current structured HTTP problem-details standard that supersedes RFC 7807. Neither standard guarantees model behavior. Platform support can change, as the Bedrock schema limitation illustrates, so compatibility testing remains part of implementation.
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 errorsNo primary source reviewed for these recommendations supplies a reliable agent-completion percentage or a causal benchmark showing that one naming scheme, error shape, or pagination strategy improves success by a stated amount. The defensible claim is narrower: explicit contracts and predictable runtime behavior give an agent better information and safer recovery paths than an API that leaves those decisions implicit.
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.
