API Capability Taxonomy for Agents: Naming the Job

An API capability taxonomy for agents is the set of job names your endpoint can be found under, and the rules that decide which listing sits under which name. It matters because an agent does not search for your product. It searches for the task it was told to complete, in whatever words its own instructions happened to use, and it takes the first usable candidate set it gets.

A human browsing a directory corrects for bad naming. They see "European Business Identity Suite," guess that it probably includes VAT number checks, and click through to find out. An agent does not guess and does not browse. It issues a query derived from a task, reads what comes back, and moves on. Every gap between the words the buyer used and the words you filed yourself under is revenue that never reaches you.

A taxonomy is a naming contract, not a folder tree

Category trees were built for humans navigating downward: Finance, then Compliance, then Tax, then your product. That structure assumes a reader who already has a rough map and is narrowing. Agents do not narrow. They arrive with a fully formed job — verify one tax number, extract line items from one invoice, resolve one company domain to a legal entity — and need to know which providers perform it.

So the unit of a capability taxonomy is a job, not a subject area. A good name answers three questions at once: what work is performed, on what input, producing what kind of result. "Tax tools" answers none of them. "Verify a VAT registration number for one company" answers all three, and a buyer reading it can tell immediately whether it matches the task in hand. This is the same principle behind grouping providers by the job they perform rather than by vendor identity — the taxonomy is just where that principle gets written down as fixed names.

Pick the granularity where substitution is honest

Granularity is the hard part, and there is a test that settles it. A capability is at the right level when any two listings under that name can be swapped without changing what the buyer asked for. Too broad and the name lies: a buyer asks for "document processing," gets five candidates, and three of them cannot read the format it holds. Too narrow and the name is useless for comparison: every bucket contains one provider, so there is nothing to compare and the score has no candidates to be relative to.

Signals that a capability is too broad:

• Listings under it disagree about required inputs, so `require_all_inputs` eliminates most of the set on every query.
• The result shapes are not comparable — one returns a boolean, another returns a full record.
• Buyers routinely filter the candidate set again immediately after receiving it.
• Two listings differ by an order of magnitude in price without differing in the work performed.

Signals that it is too narrow: single-provider buckets, names that encode a vendor's own feature branding, or names that only make sense if you already know the product. A name only an existing customer could parse is a product page, not a taxonomy entry.

Every capability needs an alias set, not a single label

One job has many phrasings. A buyer might ask for VAT validation, VAT number check, tax ID verification, or EU business number lookup, and they all mean the same call. Publishing one canonical string and hoping the query matches it is a bet you lose most of the time, because the buyer's phrasing comes from a prompt you never see.

The fix is an alias set attached to the capability itself: one canonical name that the catalogue uses in responses, and a recorded list of the other ways buyers name the same job. Aliases do the retrieval work; the canonical name does the comparison work. Keep the two jobs separate. An alias that maps to slightly different work is not a synonym, it is a mislabel, and it will put you in candidate sets you lose on compatibility rather than on price.

This is also where a provider-side discovery checklist for getting found by agents pays off: capability wording, example parameters and input schema all have to agree with the taxonomy entry, or the name promises work the endpoint does not actually accept.

Test the taxonomy against words you did not choose

A taxonomy written entirely by the people who built the API will be written in the vocabulary of the people who built the API. That vocabulary is the one failure mode you cannot notice from the inside.

Test from outside instead. Write down the job as five different people would state it — a compliance officer, a backend engineer, a founder, a support agent, an operations analyst — and run each phrasing against `GET /v1/discover?q=…` with no vendor name in the query. If your listing shows up for the engineer's phrasing and disappears for the operations analyst's, the alias set is missing a branch. Then check `GET /v1/capabilities` and `/v1/capabilities/{slug}` to confirm the job you think you offer is the job the catalogue actually lists you under, and that the candidates under it are ordered in a way that makes sense cheapest-first.

Discovery also sweeps external x402 sources, and those hits return in a separate block with no `candidate_id`. They are unreviewed and unmeasured, so they cannot chain into `/v1/compare` or `/v1/decide`. That boundary matters for taxonomy work too: an external hit appearing under a name tells you buyers use that phrasing, but it does not tell you the offer is comparable.

Renaming a capability is a migration

Names drift as products change, and renaming looks like an edit. It is not. A capability name is an address that agents, cached crawls and stored decision records all point at. Change the string and the traffic that found you under the old name stops arriving, usually without any error to alert you.

Treat a rename as a migration with an overlap period: keep the old name resolving as an alias, publish the new canonical name everywhere the old one appears, and only retire the old string once queries under it have stopped. The same care applies to the surfaces that cache your naming — your x402 discovery document and your MCP tool descriptions have to be updated in the same change, not the next sprint, or the taxonomy will disagree with itself for as long as the caches live.

Where Apiosk fits

Apiosk holds the capability layer as data rather than as prose. Each catalogue job is a named capability with a set of candidates behind it, reachable at `GET /v1/capabilities` and `/v1/capabilities/{slug}`, and the same requirement parameters — `max_price`, `max_latency_ms`, `min_reliability`, `require_all_inputs`, `optimize_for` — carry from discovery through comparison to a decision.

What that buys a provider is a name a buyer can actually reach you by, and a comparison you can recompute: every score is relative to the candidates in that one comparison, ships with the weights that produced it, and names any dimension Apiosk has not measured rather than scoring it zero. Result quality and provider terms are not measured anywhere, so the taxonomy cannot rescue a listing that is named correctly but performs badly. It can only make sure you are in the set. If you want your job listed under the names buyers actually use, that starts with listing your API and checking which capability it lands under.