Agent Readiness: Is Your Product Actually Callable?

01The short answer

Your product is agent ready when a customer's own agent can complete a real job against it end to end, using only what you publish, without a human stepping in halfway through. Not when you have an API. Not when you have shipped a connector. The test is completion, and most products fail it in a specific and repeatable set of places: authentication that assumes a person is watching, permissions that were tuned for click rates rather than call rates, errors written for a developer reading logs, an agent-facing surface that quietly disagrees with the API underneath it, and discovery documents that either do not resolve or resolve to something untrue.

The commercial stakes are simple and unpleasant. When a buyer's central agent cannot invoke your core capability, two things happen, and neither of them shows up in your funnel as a lost deal for the reason it was lost. They pick the competitor whose API is easier to hook into. Or their engineers build the thing internally while you are still scheduling the security review. A founder in one of these threads described exactly that outcome:

That is the whole argument for treating this as an engineering audit rather than a marketing item. The rest of this piece is the audit. Every check below says how to test it, because a checklist that only states what to want is a wish list. If you are evaluating somebody else's server rather than building your own, the buyer-side version of this decision lives in the MCP-first GTM stack, which covers what to connect and what a vendor should never build at all. This one is about what you ship.

02What changed in the support queue

The clearest evidence that this shift is real is not a market forecast. It is the shape of the tickets. Founders running small products, at a scale far below anything that could be called enterprise theater, describe the same change in what customers ask for, and it happened over months rather than years.

Read the last sentence again, because it is the design constraint. Not more access than they have. The same access they have. That single line settles a surprising number of architecture arguments later in this piece, and it is also the reason the permission question comes before the protocol question.

The second signal is a support ticket that will not parse against your existing categories:

This is the operational core of agent readiness and it deserves to be stated bluntly. The person paying you can no longer tell you what broke. They have lost visibility into the middle of their own workflow, on purpose, because delegating that middle is the entire point of using an agent. What reaches your support queue is not a stack trace and not an endpoint name. It is “it stopped working,” and every diagnostic burden that used to sit with a developer integrating your API has moved onto you.

Another founder framed the pace of the change in a way that is hard to dismiss:

The mobile comparison is apt in one respect and misleading in another. It is apt because the expectation arrives before the demand justifies the work, and the vendors who move early set the reference point everyone else is measured against. It is misleading because a mobile app was a visible artifact a buyer could look at. Agent readiness is invisible until it fails, and when it fails it usually fails silently. Nobody ever filed a bug saying your OpenAPI descriptions were too vague to route against.

03The gate before you build anything

Do not ship an agent surface until two conditions are already true. The most useful sentence written on this subject is also the most restrictive one:

Both halves are load bearing, and teams routinely satisfy the first while ignoring the second.

Condition one: real API-shaped workflows already exist

The test is behavioral and takes an afternoon. Pull your API logs for the last ninety days and count distinct customers who made more than a handful of calls in a session. Then look at what they were doing. If the answer is that three customers export a CSV once a month, you do not have API-shaped workflows, you have an export button with a URL. An agent surface on top of that is a surface for a job nobody is trying to do. If instead you find people chaining calls, polling for state, and reacting to results, those are the workflows an agent will pick up first, and they tell you which operations to expose before any of the others.

Condition two: the permission model survives higher frequency

This is the one that breaks products. Your permission model was almost certainly designed against a human interaction rate: a person opening a page, reading it, deciding, clicking. Agents do not pace themselves that way. A single agent may burst twenty sequential calls to finish one task, go quiet for hours, then burst again. Permission checks that were cheap at human frequency become the hot path. Quotas tuned to a person become a wall in the middle of a legitimate multi-step workflow. Row-level checks that were fine when they ran once per page load run forty times per task instead.

Test it directly rather than reasoning about it. Take one real workflow, script it as twenty sequential authenticated calls with no think time between them, run it as a genuinely restricted user rather than an admin, and watch three things: whether every authorization decision still holds, what your rate limiter does at call eleven, and what your database does when the permission subquery runs twenty times instead of once. If any of those three surprises you, fix it before you expose anything. The customer whose workflow dies at call eleven will not report a rate limit. They will report that your product does not work.

04The twelve-point callable audit

Twelve checks. Each one names the failure, then names the test. Run them in order; the early ones cause the later ones. Score honestly, because the agent will.

1. 1

   One call answers one real question

   Failure: your operations mirror your database tables, so a routine question needs five chained calls in the right order. Test it by taking the five things customers asked support last week and counting the calls an agent needs for each. More than three for a routine question means the surface is shaped like your schema, not like your product.

2. 2

   Every operation states its intent, not its mechanics

   Failure: descriptions say what an endpoint returns, not when to use it. Agents route by matching intent against your descriptions, so vague text is a routing failure, not a documentation gap. Test it by deleting the paths and operation names from your spec and handing only the descriptions to a model with a real user request. If it cannot pick correctly, neither can the agent on the other side of a customer's workspace.

3. 3

   Writes are idempotent, and the spec says which ones

   Failure: an agent times out, retries, and creates the second record. Agents retry aggressively and without asking. Test it by sending the same create request twice with the same idempotency key and confirming a single record, then sending it twice without one and looking at what you get, because that is exactly what a timed-out agent produces.

4. 4

   Errors carry a stable code, a reason, and a recovery hint

   Failure: a 400 with the message 'validation failed'. Test it by triggering your five most common failures and reading each response as though you were the model: can it distinguish retry from do-not-retry, and does it know which field to change, without fetching anything else? Section six goes deeper on this because it is the most commonly failed check on the list.

5. 5

   Rate limits are legible from inside the response

   Failure: a bare 429 with no headers, so the agent either gives up or hammers you. Test it by deliberately exhausting the limit and reading what comes back. It should carry the remaining count and a concrete Retry-After, so the agent can self-throttle instead of guessing. Then check whether your window allows a burst of twenty sequential calls at all.

6. 6

   Authentication completes without a human at an unpredictable moment

   Failure: the flow demands a browser interaction in the middle of a run, or a CAPTCHA, or an emailed link. Test it by running the entire connect flow on a machine you have never developed on, with a fresh account, following only your published instructions and nothing you happen to know.

7. 7

   The agent gets exactly the permissions the human has

   Failure: the agent path bypasses an entitlement check that the UI enforces, or the reverse, where the agent is refused something the user can plainly do in the dashboard. Test it by creating a genuinely read-only user, connecting as that user, and attempting a write. Then have them attempt a read they are entitled to and confirm it succeeds.

8. 8

   Long work is explicitly asynchronous

   Failure: a request that takes ninety seconds and might time out, leaving the agent unable to tell whether it worked. Test it by triggering your slowest operation and confirming you return an accepted status with a job id, that polling reports a terminal state, and that the failure state carries structured detail rather than a bare string.

9. 9

   The agent surface is generated from the same contract as the API

   Failure: two sources of truth that agree today. Test it by changing one field in your API and checking whether the agent surface reflects it without a second commit by a different person. If it needs one, you have drift, and drift is only ever discovered by a customer.

10. 10

    Discovery documents resolve, from outside, to something true

    Failure: a well-known document that returns correctly but describes a configuration you no longer run. Test it by curling every discovery URL you publish from outside your own network, then following each value literally, with no local knowledge filling gaps. This is check ten and it is where we failed our own audit.

11. 11

    The agent-readable docs exist at the URL you advertise

    Failure: you advertise a machine-readable path in a header or a card and it 404s. Test it by curling the exact advertised URL against production with no cookie and no session, and reading the body. Not the path you meant. The path in the header.

12. 12

    You can see the call that never happened

    Failure: the agent answers from memory instead of calling you, and nothing appears in your logs because nothing was requested. Test it by asking a client, through a normal conversation, a question your tool is supposed to own, then checking whether a call arrived. If none did, your descriptions lost to the model's prior, and no monitoring you own will ever tell you.

Checks four through eleven have enough depth to deserve their own sections, which is what the rest of this piece is. Check twelve has none, because there is nothing to instrument. It is discussed at the end of section eight.

05Auth at agent frequency

Two separate problems hide under the word authentication, and teams routinely solve the easy one and ship. The first is whether the flow can complete without a person present at the wrong moment. The second is whether the credential that results is safe to hand to something that will use it forty times in a minute and keep it forever.

On the first: any step that assumes a human is watching is a wall. Browser redirects mid-run, CAPTCHAs, interactive multi-factor prompts, links emailed to an inbox the agent cannot read. The nuance that gets missed is that a browser step at the start of a connection is fine, because the user is right there setting it up, while the identical step in the middle of an unattended run is fatal. Audit for where the human step falls, not for whether one exists.

On the second: this is where the frequency clause from section three cashes out. Consider what your product does when the same credential makes twenty authenticated calls in ninety seconds. If every call revalidates a session against your database, you have turned a login into a hot path. If your quota is a fixed window sized for a person, the agent will hit it mid-task, and the customer will experience your product as broken rather than as limited. Give agent traffic burst capacity for legitimate multi-step work, meter expensive operations by what they consume rather than by request count, and publish the numbers in headers so a well-behaved client can pace itself. An agent that can read its remaining budget will respect it. An agent that cannot will retry.

One more thing belongs in this section because it is invisible until it is not. Whatever you choose, the client id, the exact transport URL, and the scope list have to be published somewhere a client can read them. A setup that works only because a support engineer pastes a value into a ticket is not a setup, it is a manual onboarding step wearing a protocol costume. If your server does not offer dynamic client registration, the client id is a value the client fundamentally cannot discover, and it has to appear in your discovery document. That specific omission is one of the two defects we found in our own surfaces, described in section nine.

06Errors a human never sees

Write every error for a model that has no access to your docs site, no memory of your conventions, and one shot at deciding what to do next, and assume the person affected will read none of it. This is the check that reframes the most work, because it inverts twenty years of API practice. Error messages were written for a developer who would read them, understand them, search, and come back. That reader is gone from the loop. What remains on the human side is a workflow that stopped, and the customer telling you so.

A response of {"error": "validation failed"} gives an agent nothing. It cannot reason about the failure, cannot retry intelligently, and cannot recover without a human it does not have. What it will do instead is one of three unhelpful things: retry the identical request in a loop, guess at a different parameter shape, or abandon your tool and answer from its own prior. All three are worse for you than a clean failure.

Five fields turn an error from a dead end into a decision the agent can navigate.

RFC 9457 Problem Details is a reasonable envelope for all of this, and its type URI gives agents a documented place to look. The format matters less than the consistency: pick one shape, return it everywhere including from your gateway and your auth layer, and document the 4xx and 5xx responses in your spec alongside the happy path. A spec that documents only success trains the model to treat failure as an unexpected state, which is precisely when it starts inventing.

07Keeping the agent surface from drifting

The agent surface should hold no business logic of its own. Not less logic. None. This is the single design decision that determines whether you are maintaining one product or two, and the team that put it most clearly framed it as a feature rather than a limitation:

Note the causal chain in that sentence, because it is doing more work than it looks. Same endpoints implies same key, which implies identical rate limits and identical permissions, which means the second surface inherits every guarantee the first one has already been tested for. And zero new logic is what makes drift structurally impossible rather than merely unlikely.

Drift is worth describing precisely because it is rarely dramatic. It starts as a convenience. A tool needs a slightly different default, so it sets one. A tool wants to filter out archived records because that is nearly always what the caller means, so it filters. Six months later a customer says the agent reported eleven items and the dashboard shows fourteen, and you spend a day discovering that a default in the tool layer diverged from a default in the API. Nobody was wrong at any individual step. There were simply two places where the behavior lived and only one of them had a test.

The test for check nine is mechanical. Change one field in your API. Do not touch anything else. Then look at whether the agent surface reflects the change with no further human action. If it needs a second commit, by a different person, in a different file, you have two sources of truth, and the only question left is how long until they disagree.

One caveat, since dumb wrapper is easy to over-apply. Shaping is not logic. Exposing one operation per real user intent rather than one per database table is a shaping decision, and it is the right one: teams who have built dozens of these converge on it because fine-grained operations force the model to spend its budget deciding what to call. Composing three internal calls behind one intent-shaped operation is fine. Inventing a rule that exists nowhere else in your product is not. The distinction is whether a customer could observe a different answer from the two surfaces.

There is also a governance corollary that is easy to skip. If you keep the tool layer thin, every new integration should ship its agent-facing operation in the same change as the integration itself, not in a later phase. A capability that exists only in your web app is a capability most users will never reach once their workspace is an assistant. We hold ourselves to this, and the reasoning behind it is set out in our writeup on working from an AI assistant.

08Discovery documents that actually resolve

Discovery documents are the only part of your product that is consumed exclusively by machines, which means every defect in them is silent by construction. No human opens your server card on a Tuesday to see how it is doing. Nothing renders wrong. Your uptime monitor is green. The failure surfaces as a customer saying the connection did not work, and it surfaces as whatever kind of failure your broken document happened to produce, which is almost never the kind of failure it actually is.

There are three distinct ways these documents fail, in increasing order of how hard they are to notice.

One: the document does not resolve

The advertised URL 404s. This is the easiest to find and the easiest to miss, because you will test it with a path you remember rather than the path you published. Test it by extracting the URL from the artifact that advertises it, programmatically, and curling that string against production from outside your network with no cookie. Framework routing conventions are a common cause here and are covered in section nine, because one of them cost us.

Two: the document resolves but describes something you no longer run

Worse, because it returns cleanly. A card declares one authentication scheme while pointing at a transport that expects a different one. A client follows the document faithfully, does exactly what it says, and fails. Then the failure is reported to you in the vocabulary of the last step that broke, which is usually authentication, and you spend a day debugging an auth system that is working perfectly. Test it by following your own document literally, as a client would, using no local knowledge to fill any gap.

Three: the document is true but incomplete

The subtlest one. Everything present is accurate, and something a client cannot obtain any other way is missing. A partial capability list means an agent never learns that the operation it needed exists, so it does not call you and nothing in your logs records the absence. A missing client id, on a server that does not offer dynamic client registration, means the connection cannot be completed at all by a client that has only your document. Test it by asking, for each value you left out, whether a client could derive it from anything else you publish. If the answer is no, it is not an omission, it is a broken document.

Which brings us back to check twelve, the one with no test harness. When discovery is thin, the failure mode is not an error at all:

You cannot instrument an absence. The only approximation is periodic manual probing: take the questions your product is supposed to own, ask them the way a customer would inside a real client, and check whether a call arrived. When none did, the fix is almost never in your infrastructure. It is in the descriptions, which lost to the model's own prior.

09What we found when we audited ourselves

We ran this checklist against our own product while writing it and failed two of the twelve checks. Both were live defects. Both are fixed as of September 2, 2026. We are describing them in detail because a readiness checklist written by somebody who has never failed one is a sales document, and because these two failures are unusually good illustrations of why discovery defects go undetected.

Defect one: a server card that described a server we were no longer pointing people at

Our machine-readable server card at /.well-known/mcp/server-card.json declared an authentication type of OAuth 2.1 while its transport URL still pointed at our legacy header-credential server. Those two facts cannot both be acted on. A client reading the card would complete an entire OAuth authorization flow, obtain a valid token, and then post to a server that wanted header credentials instead and had never heard of that token.

The consequence is the part worth internalizing. The client does not report “your discovery document is internally inconsistent.” It reports that authentication failed, because authentication was the last thing it tried. So the defect presented as an auth bug in a system that was working exactly as designed. Anyone investigating it would start in the OAuth code and find nothing wrong, because nothing was wrong there. This is failure mode two from the previous section, and it is the reason that check reads “resolves to something true” rather than just “resolves.”

The same card had two incompleteness problems. It listed 9 of our 65 tools, which means an agent reading it to decide whether we could answer a question would have concluded, correctly given what it was told, that we could not. And it omitted the client id. Our server does not offer dynamic client registration, so the client id is the one value a client cannot discover for itself by any means. Leaving it out did not make the document terse. It made the document insufficient to complete a connection. The card now declares OAuth 2.1 with PKCE, the current transport at mcp.linkeddit.com/mcp, the client id linkeddit-mcp-claude with no client secret required, and all 65 tools.

Defect two: agent-readable documentation at a URL that had never once served

We publish a markdown version of our pages for agents that would rather read text than parse a rendered page, and we advertise it with a Link header on every response so a client does not have to guess where it lives. Correct instinct. The file lived at /__agent/home.md.

The Next.js App Router treats a folder whose name begins with an underscore as a private folder and excludes it from routing entirely. That is documented, intentional framework behavior, and it is a perfectly reasonable convention for colocating files you do not want to become routes. It also meant the URL returned 404 in development and in production, from the day it shipped, while a header on every single response told agents to go fetch it. It had never once served. Not to an agent, not to us, not to anyone.

Nothing about that failure was visible from inside the product. No page looked broken. No test failed, because no test asserted that an advertised URL resolves. Our own analytics showed nothing, since a 404 on a path nobody links to does not stand out. The only way to find it is the test in check eleven: take the URL out of the header programmatically and curl exactly that string against production. The docs now live at a path without the underscore prefix and return 200.

10What the buyer's IT team checks now

Once IT is in the evaluation and the company already runs an agent stack, callability stops being a differentiator and becomes a filter. The distinction matters for how you prioritize: a differentiator earns you points, and a filter decides whether you are on the list at all. Practitioners describe the change arriving with a specific trigger:

Take the two-quarter estimate as a community observation rather than a forecast, but note that the underlying mechanism is not speculative. The same discussion supplies the reason it hardens into a filter: if a product has no agent-callable surface, plugging it into an existing agent stack requires months of custom engineering work, and that cost lands on the buyer's team rather than yours. A buyer with a platform team and a roadmap will not absorb that cost for a tool they can substitute.

What that review actually looks like, in the order it tends to be asked:

Read that table as a product spec, because it is one. Every row is an engineering commitment that has to exist before the review, not a document produced during it. Approval gates and audit records in particular are exactly the kind of capability a chat session cannot provide, which is the reason they are legitimate things for a vendor to build rather than defer to the client. The complementary question, which capabilities a vendor should refuse to build at all, is worked through in the MCP-first GTM stack.

One last piece of realism, since this category attracts overstatement. Adoption is still smaller than the discourse suggests. Vendors who have shipped report that a minority of users ask for agent access, and that the request comes from the technical buyer well before the economic buyer knows the term. That is an argument about sequencing, not about whether to do it. The technical buyer is usually the one who blocks a deal, the platform team is the one who builds the internal replacement, and the warm lead that goes cold because somebody's engineers shipped it first does not come back.

Frequently asked questions

Sources

• Zuplo: The API Readiness Gap, How to Design APIs That AI Agents Can Actually Use (March 2026)
• Apideck: API Design Principles for the Agentic Era (February 2026)
• freeCodeCamp: How to Design APIs for AI Agents (May 2026)
• RFC 9457: Problem Details for HTTP APIs
• Cloudflare: bot traffic trends, automated traffic surpassing human traffic
• Next.js documentation: project structure and private folders (an underscore prefix opts a folder out of routing)
• Scalekit: API Access Patterns for AI Agents (March 2026)

Community quotes are verbatim and attributed to the platform they were published on, never to an individual account. The developer survey figures are quoted from the Postman State of the API Report as reported by Zuplo, and should be read as of that report's publication. The two defects described in section nine were found in our own production surfaces while writing this article and were fixed on September 2, 2026; the configuration values quoted are the current ones.