API metadata agents actually read is metadata that changes whether an endpoint enters a candidate set, whether a valid request can be built, or whether the buyer is allowed to pay. For a provider, the useful test is not whether a field looks complete in documentation. It is whether removing that field would change the agent's next action.
This separates operational metadata from catalogue decoration. An agent needs to map a task to an operation, satisfy the request contract, predict the response shape and apply its constraints. A company history, broad category label or polished feature sentence may help a human reader, but it does not complete any of those steps.
Start with the job, not the product category
The first field an agent uses is the operation description. It should name one action and one result. “Enrichment platform” names a market. “Return a normalized company profile for a submitted domain” names work that can be matched to a task.
The strongest descriptions carry four pieces of information in one or two sentences:
- The action the endpoint performs.
- The subject or input it acts on.
- The result one successful call returns.
- A material limit that changes task fit.
Keep the operation name stable and programmatic. In OpenAPI, an operationId gives the operation a unique handle, while summary and description explain its behavior. In MCP, a tool definition similarly separates name, title and description. The human-readable title can change without forcing every integration to relearn the callable identifier.
This is the practical distinction behind capability-based API discovery. Agents search for a job they need completed. Provider names and internal product families become useful only after the capability match exists.
Input schemas decide whether the endpoint is callable
A description can retrieve a candidate, but the input schema determines whether the agent can use it. The fields that change behavior are the required list, property types, parameter locations, enum values, formats, defaults and documented limits.
Required must mean required at the deployed endpoint. An omitted field should either have a valid default or produce a named validation error. If two inputs depend on each other, state the dependency in the schema where the format allows it and repeat it briefly in the operation description when it changes selection.
Examples are useful as tests, not as substitutes for a contract. Validate each published example against the same request validation used in production. A copied example with a retired field teaches an agent to make a request that cannot succeed.
Input compatibility also affects comparison. Apiosk can apply require_all_inputs to remove candidates that cannot accept the supplied values. It can report compatibility because the input mapping is explicit. It cannot recover a required field that exists only in a tutorial paragraph.
Output metadata answers whether the result fits
An agent needs more than a promise that the call “returns data.” Publish the response media type, stable top-level fields, their types, and the difference between a successful response and an operational error. An output schema is preferable when the result is structured. A representative example helps when the schema permits broad objects, but it should not contain customer data or imply guarantees.
Name limits that change fitness for the task. If the endpoint returns one record rather than a collection, say so. If a field may be absent, make it optional instead of showing it in every example. If a response contains a continuation token, describe the condition that produces it.
Do not turn output metadata into an unsupported quality claim. Apiosk does not measure result quality or provider terms. Those dimensions are not assigned zero; they are outside the score. The x402 discovery document checklist applies the same rule: describe what one call returns before asking a buyer to pay for it.
Payment and policy fields remove impossible candidates
For a paid API, price is not a footer note. It is a constraint input. The agent may have a maximum price, an allowed settlement route or a rule about whether direct settlement is acceptable. Current payment terms therefore need to remain attached to the callable resource.
Do not copy a list of rails, tokens or prices into several descriptions. Those values drift. For Apiosk, the gateway's well-known x402 document is the live source of truth. The integration page for agent buyers shows how to call the service, while the gateway response supplies the terms that apply now.
Other policy metadata matters when it changes whether a request is safe or permitted. Authentication requirements, data residency constraints, retention statements and side effects should be linked to the specific operation they govern. MCP tool annotations can describe read-only, destructive, idempotent and open-world behavior, but they are hints rather than enforcement. A provider still has to make the service behave as described.
Stable identity and freshness keep records joinable
Discovery metadata is rarely consumed once. A crawler fetches it, a catalogue normalizes it, and a later agent reads the cached record. Stable identifiers let those systems replace an old version instead of creating a second candidate that looks similar.
Give the provider, resource and operation separate identities. Keep the callable URL and method explicit. Publish an update time or version that changes when the contract changes. Use a canonical documentation URL for details that do not fit in the record.
Freshness matters most for fields that affect execution: request shape, authentication, payment terms and availability. A release check should compare the public record with the deployed route. Test a valid request, a missing required input, and the live unpaid response. This catches drift before a crawler distributes it.
The guide to how AI agents discover APIs explains why cached text makes this discipline important. Updating a marketing page does not repair a stale machine-readable record somewhere else.
Metadata that usually does not change the call
Some fields are not useless, but they should not displace the operational contract. Long company descriptions, award lists, broad tags, logo variants and repeated slogans rarely help construct a request or apply a buying constraint. A large synonym list can also weaken the capability signal by making one endpoint appear suitable for unrelated jobs.
Treat decorative metadata as a presentation layer. Keep it after the fields required for retrieval, validation and execution. Then run a deletion test: if removing a sentence changes no candidate filter, input value, expected output, safety decision or payment rule, it is not core agent metadata.
The same test exposes duplicated prose. A parameter description belongs beside that parameter. A payment rule belongs with the live payment requirements. A constraint should have one authoritative machine-readable location, with human documentation explaining rather than redefining it.
Where Apiosk fits
Apiosk turns agent-readable metadata into a three-step buying path. GET /v1/discover?q=… returns a candidate set with stable candidate IDs. GET /v1/compare places price, measured latency, measured success rate and input compatibility side by side. GET /v1/decide returns one provider, the rule that selected it, each rejected candidate with the exact removing constraint, and the runners-up in order.
The 0–100 comparison score is relative to that candidate set. Each response includes the weights and every candidate's contribution. Dimensions that Apiosk has not measured are dropped and named, not silently scored as zero.
External x402 hits remain in a separate external_candidates block. They are unreviewed, unmeasured, have no candidate ID and cannot enter comparison, decision or Apiosk settlement. Providers that want a reviewed candidate can list an API on Apiosk with the capability, request contract and current operating facts attached.
The metadata has done its job when the buyer can explain five things without guessing: what the endpoint does, how to call it, what comes back, which constraints apply and why it remained in the candidate set.
Frequently asked questions
Which API metadata does an agent need before selecting an endpoint?
An agent needs a task-level capability description, a stable operation identifier, required inputs with types and constraints, the expected output shape, and the current payment terms. Operating facts such as side effects, authentication, and observed performance matter when they can remove the endpoint from consideration.
Does a longer API description make a tool easier for agents to use?
Not by itself. A short description that names the action, result, required subject, and material limit gives a buyer more usable information than a long company narrative. Put request rules in the input schema instead of relying on prose.
Are MCP annotations enough to guarantee safe tool use?
No. MCP defines annotations such as read-only, destructive, idempotent, and open-world behavior as hints, and clients should not treat untrusted hints as proof. Providers should align those fields with the endpoint's real behavior and enforce safety in the service itself.
Can external x402 metadata enter an Apiosk comparison automatically?
No. Apiosk returns external x402 hits separately without a candidate ID because they are unreviewed, unmeasured and not settleable through Apiosk. Only reviewed catalogue candidates can chain into comparison and decision.