DEV Community: Paul Spread

Inside an Agent Readiness Scanner: Rules, Evidence and Reproducibility

Paul Spread — Fri, 28 Aug 2026 12:09:49 +0000

Originally published at AgentBadge.

When someone tells you that an API has an 87/100 Agent Readiness score, the first question should not be:

"Is 87 a good score?"

The better question is:

"Why is it 87?"

And the question after that is even more important:

"Can I reproduce the result myself?"

This is the problem AgentBadge is designed to solve.

Agent Readiness should not be an opinion generated by an LLM. It should be a measurable property of a service, calculated from explicit rules and supported by evidence.

The core idea is simple:

Rules → Evidence → Assertions → Score → Report

This article explains what happens inside that pipeline.

1. A scanner should measure, not guess

Imagine two tools scanning the same API.

Tool A says:

"Your API appears to be highly suitable for AI agents."

Tool B says:

"AB-004 passed because https://example.com/openapi.json returned HTTP 200 and contained a valid OpenAPI document."

Which result would you trust?

The second one is much more useful.

It tells you:

what was checked;
what rule was applied;
what evidence was found;
why the rule passed or failed;
and where the evidence came from.

This is the fundamental design principle behind AgentBadge:

Every meaningful score should be explainable through evidence.

The scanner should not ask an AI model:

"How agent-ready does this API feel?"

It should ask deterministic questions such as:

"Does this URL exist?"

"Does it return the expected content type?"

"Does the response contain an OpenAPI document?"

"Does the declared authentication mechanism contain the required information?"

The difference may look subtle, but architecturally it is enormous.

2. Rules are the measurement instrument

A scanner is only as trustworthy as its rules.

Instead of hiding the evaluation logic inside application code, AgentBadge treats rules as explicit, versioned measurement definitions.

A simplified rule might look conceptually like this:

AB-001
Name: OpenAPI discoverability

Given:
  target = https://example.com

Check:
  GET /.well-known/openapi.json

Pass when:
  HTTP status = 200
  AND response is valid OpenAPI

Evidence:
  URL
  HTTP status
  content type
  content hash

Severity:
  medium

The important property is that another implementation should be able to understand the same rule.

The rule is not:

"The API looks well documented."

It is:

"This specific machine-readable artifact was found and passed these specific checks."

That makes the scanner much easier to test, audit and reproduce.

3. Deterministic before intelligent

This leads to one of the most important architectural principles of AgentBadge:

Deterministic before intelligent.

If something can be established deterministically, use deterministic logic.

For example:

Question	Preferred method
Does robots.txt exist?	HTTP request
Does sitemap exist?	HTTP request + parser
Does OpenAPI exist?	HTTP request + schema validation
Is JSON valid?	JSON parser
Does declared endpoint exist in another document?	Exact matching
What does an undocumented endpoint mean?	AI-assisted inference
What does an API capability actually mean?	Human confirmation / assisted review

AI has a role, but it should not become the judge of facts that can be verified directly.

An LLM can help interpret ambiguous documentation.

It should not silently decide that an API supports refunds simply because a paragraph mentions the word "refund."

This is why AgentBadge treats AI as a copilot, not as the authority responsible for the score.

4. Evidence is the missing layer

A score without evidence is difficult to trust.

Consider this finding:

Documentation: 18/25

There is almost nothing you can do with it.

Now consider:

AB-007  OpenAPI discoverability

STATUS: VERIFIED

Evidence:
GET https://api.example.com/openapi.json
HTTP 200
Content-Type: application/json

OpenAPI version:
3.1.0

Confidence:
1.00

Now the developer knows what happened.

They can inspect the same resource themselves.

This creates a chain:

HTTP response → Evidence → Assertion → Rule result → Category score → Overall score

The evidence is therefore not an optional explanation attached to the report.

Evidence is part of the measurement itself.

5. Assertions connect evidence and scoring

A useful internal abstraction is an assertion.

An assertion answers one concrete question.

For example:

{
  "rule_id": "AB-007",
  "status": "VERIFIED",
  "target": "https://api.example.com/openapi.json",
  "evidence": {
    "http_status": 200,
    "content_type": "application/json"
  },
  "confidence": 1.0
}

The important states are intentionally explicit.

VERIFIED

The scanner found direct evidence supporting the assertion.

INFERRED

The scanner has a reasonable interpretation, but the evidence is not sufficient to treat it as fact.

CONFLICT

Two sources disagree.

For example:

Guide says: POST /refund
OpenAPI says: POST /refund-request

MISSING

The expected capability or artifact could not be found.

These states are more informative than a simple pass/fail system.

They tell us not only what the scanner thinks, but also how strongly it knows it.

6. Confidence is not the same as verification

This distinction is important.

A scanner may infer something with high confidence.

That does not automatically make it verified.

For example, an API documentation page might strongly suggest that a service supports refunds.

An LLM may assign a confidence of 0.94 to that interpretation.

But unless there is machine-readable evidence supporting the capability, the assertion should not magically become VERIFIED.

Instead: INFERRED, confidence: 0.94

The user can then: Confirm, Edit, Reject

This is the boundary between automatic fixes and assisted fixes.

Safe, deterministic changes can be automated.

Semantic claims require human confirmation.

7. Reproducibility matters

Now we arrive at the second major property of the scanner.

Suppose you scan https://api.example.com today and receive 76/100.

Someone else runs the same rules against the same captured state and should be able to understand how the result was produced.

That requires more than storing the final number.

The report needs to describe the measurement context.

Conceptually:

{
  "target": "https://api.example.com",
  "ruleset": "agent-readiness-v1.0",
  "scanner_version": "0.1.0",
  "timestamp": "...",
  "assertions": [...],
  "score": {
    "total": 76,
    "categories": {
      "discovery": 18,
      "documentation": 20,
      "authentication": 17,
      "machine_readability": 21
    }
  }
}

This allows the score to be understood as the output of a defined measurement process rather than a mysterious number.

8. Rules must be versioned

Rules change. New standards appear. New machine-readable formats emerge.

Some checks eventually turn out to be too strict or too weak.

Therefore: Agent Readiness v1.0 must not silently become v1.1 while pretending the results are identical.

Each ruleset should have an explicit version.

Now a report can say: Score: 82/100, Ruleset: Agent Readiness v1.2

This gives us an important property:

Same target + same measurement state + same ruleset = reproducible result.

9. Why open rules do not destroy the product

If AgentBadge publishes its rules, can't someone simply copy them?

Yes. And that is intentional.

The goal is not to create a secret scoring algorithm. The goal is to establish a useful measurement standard.

The long-term value comes from the workflow around that standard: open specification, open scanner, GitHub Action, README badge, continuous monitoring, regression alerts, fix workflow, developer adoption.

A competitor can copy AB-001, AB-002, AB-003.

They cannot instantly copy: thousands of repositories displaying the badge, existing GitHub Actions, developer habits, historical scan data, integrations, workflow configuration, trust built around independently verifiable reports.

The moat is not secret rules. It is a standard installed inside the developer workflow.

10. The score should explain itself

A single number is useful for quick comparison. But it should never be the only information available.

Suppose a developer's score changes: 76 to 72.

The product should explain the delta: +8 OpenAPI documentation detected, -12 New authentication issue detected, +0 Discovery unchanged. Result: 76 to 72.

This turns measurement into an improvement loop.

11. From Measure to Prove to Improve

The architecture becomes a simple loop: Measure, Prove, Improve, Measure again.

The score is the beginning of the workflow, not the end.

12. What AgentBadge should never claim

AgentBadge measures Agent Readiness.

It does not certify: API security, business correctness, service reliability, legal compliance, quality of business logic, whether an agent should trust the company.

A high score does not mean "This API is safe." It means "This API satisfied these measurable Agent Readiness criteria."

Don't certify. Measure.

13. What this enables

Once the measurement layer exists, many higher-level products become possible.

A developer can run npx @agentbadge/cli scan https://api.example.com.

A CI pipeline can enforce a minimum score. A README can display the current measurement. A platform can query AgentBadge programmatically. An organization can compare vendors using the same ruleset.

14. The bigger idea

The web has spent years developing tools for measuring websites. Performance has metrics. Accessibility has automated checks. Security has scanners. TLS has analyzers. SEO has crawlers and validators.

The emerging agentic web needs something similar.

AgentBadge's approach is deliberately conservative: Define the rules. Collect the evidence. Show the reasoning. Version the rules. Make the result reproducible.

That is what makes Agent Readiness a measurement discipline rather than another AI-generated checklist.

Read more:

What Is Agent Readiness? — Article 1
Why AI Agents Fail to Use APIs — Article 5
What Does an AI Agent Need to Understand an API? — Article 6
Why Your OpenAPI Spec Isn't Enough — Article 7
How Do You Measure Agent Readiness? — Article 8

Agent Knowledge Layer: agentbadge.xyz/agent-guide

Inside an Agent Readiness Scanner: Rules, Evidence and Reproducibility

Paul Spread — Fri, 28 Aug 2026 06:26:46 +0000

Originally published at AgentBadge.

When someone tells you that an API has an 87/100 Agent Readiness score, the first question should not be:

"Is 87 a good score?"

The better question is:

"Why is it 87?"

And the question after that is even more important:

"Can I reproduce the result myself?"

This is the problem AgentBadge is designed to solve.

Agent Readiness should not be an opinion generated by an LLM. It should be a measurable property of a service, calculated from explicit rules and supported by evidence.

The core idea is simple:

Rules → Evidence → Assertions → Score → Report

1. What the scanner actually does

The scanner does not ask an LLM "is this API good?"

It runs deterministic checks:

Does robots.txt exist?
Does /.well-known/openapi.json return 200?
Is the response valid OpenAPI?
Does the homepage have machine-readable metadata?
Is there an agents.txt file?
Are there llms.txt or llms-full.txt files?
Does the API support content negotiation?
Is there an A2A agent card?

Each check produces evidence. Each piece of evidence becomes an assertion. Each assertion has a status.

AI-assisted inference is used when deterministic checks are insufficient — but it is a copilot, not the judge.

2. Rule structure

Every rule follows the same structure:

AB-001
Name: OpenAPI discoverability

Given:
  target = https://example.com

Check:
  GET /.well-known/openapi.json

Pass when:
  HTTP status = 200
  AND response is valid OpenAPI

Evidence:
  URL
  HTTP status
  content type
  content hash

Severity:
  medium

This is not a prompt. It is a specification.

The rule says what to check, what constitutes a pass, and what evidence to collect.

3. Assertion states

Every assertion has exactly one of four states:

State	Meaning
VERIFIED	Direct evidence found
INFERRED	Reasonable interpretation, insufficient evidence
CONFLICT	Two sources disagree
MISSING	Expected capability or artifact not found

An LLM can be 94% confident that an API supports refunds. Without machine-readable evidence, the assertion stays INFERRED.

Confidence is not the same as verification.

4. Evidence is part of the measurement

Evidence is not an optional explanation attached after the fact.

Each finding includes:

The actual HTTP response (where applicable)
The URL checked
The content type received
A content hash
The timestamp of the check

This means the assertion is not just "OpenAPI exists: yes" — it is "OpenAPI exists: yes, here is the proof."

{
  "rule_id": "AB-007",
  "status": "VERIFIED",
  "target": "https://api.example.com/openapi.json",
  "evidence": {
    "http_status": 200,
    "content_type": "application/json"
  },
  "confidence": 1.0
}

5. Scoring has category floors

The total score is not a simple average.

Some categories are foundational. If Discovery = 0, it does not matter how good the documentation is — agents cannot find the API.

Category floors prevent a high score from hiding a critical zero.

A score of 91/100 with Discovery = 0 is not a good score. It is a misleading one.

6. What confidence means and what it does not

An LLM can analyze an API documentation page and say:

"This API likely supports token-based authentication with rate limiting."

That is a reasonable inference. But without machine-readable evidence (an OpenAPI spec, a response header, a well-known endpoint), it remains INFERRED.

The user can then:

Confirm — "Yes, this is correct, I checked manually"
Edit — "Almost right, but the auth method is different"
Reject — "No, this is wrong"

This creates a feedback loop: automatic fixes for deterministic changes, human confirmation for semantic claims.

7. Reproducibility

If the scanner gives a score of 76/100 for https://api.example.com today, someone else running the same rules against the same captured state should be able to understand how the result was produced.

The report needs to describe the measurement context:

{
  "target": "https://api.example.com",
  "ruleset": "agent-readiness-v1.0",
  "scanner_version": "0.1.0",
  "timestamp": "...",
  "assertions": [...],
  "score": {
    "total": 76,
    "categories": {
      "discovery": 18,
      "documentation": 20,
      "authentication": 17,
      "machine_readability": 21
    }
  }
}

8. Rules must be versioned

Rules change. New standards appear. Some checks eventually turn out to be too strict or too weak.

Agent Readiness v1.0 must not silently become v1.1 while pretending the results are identical.

Each ruleset has an explicit version. A report can say:

Score: 82/100

Ruleset: Agent Readiness v1.2

Same target + same measurement state + same ruleset = reproducible result.

9. Why open rules do not destroy the product

If AgentBadge publishes its rules, can't someone simply copy them?

Yes. And that is intentional.

The goal is not a secret scoring algorithm. The goal is a useful measurement standard.

The long-term value comes from the workflow around that standard:

Open specification → Open scanner → GitHub Action → README badge → Continuous monitoring → Regression alerts → Fix workflow → Developer adoption

A competitor can copy rules. They cannot instantly copy:

thousands of repositories displaying the badge
existing GitHub Actions
developer habits
historical scan data
integrations
trust built around independently verifiable reports

The moat is not "our rules are secret." It is "our standard is installed inside the developer workflow."

10. The score should explain itself

If a developer's score changes from 76 → 72, the product should explain the delta:

+8  OpenAPI documentation detected
-12  New authentication issue detected
+0   Discovery unchanged

Result: 76 → 72

Without a breakdown, a developer who fixed three problems and still sees the score decrease will think the product is broken.

With a breakdown, it becomes: "The scanner found something new. Now I know what to fix."

11. From Measure to Prove to Improve

The architecture is a loop:

MEASURE → PROVE → IMPROVE → Measure again

The score is the beginning of the workflow, not the end.

12. What AgentBadge should never claim

AgentBadge measures Agent Readiness. It does not certify:

API security
business correctness
service reliability
legal compliance
whether an agent should trust the company

A high score means: "This API satisfied these measurable Agent Readiness criteria."

Don't certify. Measure.

13. What this enables

npx @agentbadge/cli scan https://api.example.com

A CI pipeline can enforce a minimum score. A README can display the current measurement. A platform can query AgentBadge programmatically. An organization can compare vendors using the same ruleset.

14. The bigger idea

Performance has metrics. Accessibility has automated checks. Security has scanners. TLS has analyzers. SEO has crawlers and validators.

The emerging agentic web needs something similar.

Don't ask an AI to invent a score.

Define the rules. Collect the evidence. Show the reasoning. Version the rules. Make the result reproducible.

Then let developers improve their systems.

Read more:

What Is Agent Readiness? — Article 1
Why AI Agents Fail to Use APIs — Article 5
What Does an AI Agent Need to Understand an API? — Article 6
Why Your OpenAPI Spec Isn't Enough — Article 7
How Do You Measure Agent Readiness? — Article 8

Agent Knowledge Layer: agentbadge.xyz/agent-guide

How Do You Measure Agent Readiness?

Paul Spread — Wed, 26 Aug 2026 13:11:26 +0000

If Agent Readiness is real, it should be measurable. And the measurement should be reproducible.

You've read about what Agent Readiness is. You've seen why AI agents fail to use APIs and what an agent needs to understand. You know why OpenAPI alone isn't enough.

Now the question shifts from "what" to "how":

How do you objectively determine whether an API is ready for AI agents?

This article introduces a measurement framework for Agent Readiness — one built on deterministic checks, evidence, and reproducibility. Not opinions. Not LLM scores. Measurable properties that any scanner can verify.

The Measurement Problem

Labels like "AI-friendly API", "Agent-ready", and "Optimized for AI" are everywhere. They sound useful. They aren't.

Two auditors can look at the same API and disagree on whether it's "agent-friendly." An LLM can score the same API differently on different runs. A marketing page can claim "AI-optimized" without any way to verify what that means.

The problem isn't that these labels are wrong. The problem is that they're not reproducible. If two people can look at the same API and reach different conclusions, the measurement isn't real — it's an opinion.

If Agent Readiness is a real property of an API, it should be measurable. And the measurement should satisfy a simple requirement:

same URL + same ruleset + same point in time = same result

This is the reproducibility requirement. It's what separates measurement from opinion.

What Should We Measure?

Agent Readiness isn't a single number. It's a set of properties across four categories:

Discovery — Can an agent find the API?
Documentation — Can an agent understand the API?
Authentication — Can an agent authenticate autonomously?
Machine Readability — Can an agent interact machine-to-machine?

But these aren't just checkboxes. Each category contains specific, testable assertions — properties that can be verified with HTTP requests:

Discovery
  ✓ OpenAPI is discoverable
  ✓ llms.txt exists
  ✓ Documented API entry point exists

Authentication
  ✓ Authentication mechanism is declared
  ✓ Required credentials are documented
  ✓ Protected endpoint behavior is understandable

The question isn't "does the API have OpenAPI?" The question is "can we verify that OpenAPI is discoverable?" — and that's a testable property.

Deterministic Before Intelligent

This is the central principle of the measurement framework.

First:

HTTP response → Rule → Evidence → Result

Then, AI can help interpret complex cases. But the AI is a copilot, not the primary engine.

The wrong approach:

URL → LLM → "Looks agent-ready: 76/100"

The right approach:

URL → Deterministic scanner → Evidence → Rules → Score → AI copilot (optional)

This is what distinguishes AgentBadge from an AI auditor. Deterministic checks are reproducible — same input, same output, every time. LLM assessments are not. An LLM might score the same API as 76 today and 82 tomorrow. A deterministic scanner will give you the same result as long as the API hasn't changed.

This doesn't mean AI is useless. AI is excellent at interpreting ambiguous evidence, suggesting fixes, and explaining results. But the measurement itself — the check, the evidence, the score — should be deterministic.

Evidence, Not Opinions

Every assertion in the measurement framework comes with evidence. Not "we think this is true" — but the actual HTTP response that proves it.

Here's what an evidence card looks like:

OPENAPI_DISCOVERABLE
Status: VERIFIED

Evidence:
  GET /openapi.json
  HTTP 200
  Content-Type: application/json
  Valid OpenAPI document

This is the key difference between measuring and certifying. A certification says "this API is agent-ready." An evidence card says "here is the HTTP response that proves OpenAPI is discoverable."

Don't tell developers what to believe. Show them what we measured.

When every assertion includes evidence, the conversation changes. Instead of debating whether an API is "ready," you can point to specific findings: 72 checks run, 58 passed, 14 failed — here's the evidence for each.

Assertions

A scan result is not a magic score. It's a set of assertions — each one testable, each one with a status and evidence:

Assertion	Status	Evidence
OpenAPI discoverable	VERIFIED	`/openapi.json → 200`
Authentication documented	VERIFIED	`securitySchemes` present in spec
Machine-readable errors	MISSING	HTML error response, not structured
Agent guide	MISSING	`404 /agent-guide.json`

This table is the heart of the measurement. Before you look at the score, you look at the assertions. Each assertion tells you something specific about the API — and each one is independently verifiable.

VERIFIED / INFERRED / CONFLICT / MISSING

Every assertion has one of four statuses:

VERIFIED — Direct proof exists. The scanner found the evidence.
MISSING — Not found. The scanner looked and didn't find it.
INFERRED — There are reasonable grounds to believe this is true, but the evidence is insufficient for verification.
CONFLICT — Two sources contradict each other.

Here's a real example of CONFLICT:

OpenAPI spec says:    POST /refund
Agent Guide says:     POST /refund-request

Two sources, same API, different paths. The assertion status is CONFLICT — not VERIFIED, not MISSING. The scanner can't verify which is correct without making a live request, so it flags the contradiction.

The distinction between INFERRED and VERIFIED matters. INFERRED means "this looks right, but we can't prove it." VERIFIED means "here's the proof." An API that claims to have structured errors but returns text/html on error responses isn't VERIFIED — it might be INFERRED or MISSING depending on what the scanner found.

Confidence is not the same thing as verification.

Scoring

Only after assertions are established do we compute a score. The score is derived from the assertions — not the other way around.

Discovery           18/20
Documentation       19/25
Authentication      17/20
Machine Readability 15/20
Verification        10/15
─────────────────────────
Total               79/100

There's a critical rule in the scoring model: category floor. A high total score should not hide a critical zero in a fundamental category.

If Discovery = 0, the API is effectively invisible to agents. No amount of excellent documentation or perfect authentication can compensate for the fact that agents can't find the API. A score of 91/100 with Discovery = 0 is misleading — it suggests the API is nearly ready when it's actually missing the most fundamental layer.

The category floor prevents this. If any critical category is zero, the total score is capped. A high score should reflect actual readiness, not average out a fatal gap.

A high score should not hide a critical zero.

Score ≠ Certification

AgentBadge doesn't say "this API is safe" or "this API is approved for agents."

It says: "Here is what we measured, under this ruleset, at this point in time."

This distinction matters for three reasons:

Trust — Developers can verify the evidence themselves. They don't need to trust a badge; they can check the proof.
Legal risk — Certification implies endorsement. Measurement implies observation. AgentBadge observes and reports; it doesn't endorse.
Reproducibility — Anyone can run the same checks and get the same results. The measurement is transparent, not opaque.

Don't certify. Measure.

Reproducibility

A measurement is only useful if it can be independently verified. The reproducibility formula is:

URL + timestamp + ruleset version + scan artifact + report hash

Example:

Agent Readiness v1.0
Scan: 2026-08-26T14:03:22Z
Ruleset: agentbadge-ruleset@1.0.0
Report hash: a3f7b2c1...
Score: 79/100

Every scan records the URL, the timestamp, the ruleset version, and produces a report hash. The scan artifact is preserved. Another scanner — or another developer — can run the same checks against the same URL with the same ruleset and verify the results.

This is what makes the measurement real. It's not a subjective assessment that changes with the auditor. It's a deterministic process that produces the same output for the same input.

Static Measurement vs Real Agent Behavior

An honest caveat: static readiness does not prove that every AI agent will successfully use an API.

AgentBadge measures whether an API can be discovered, understood, and potentially used by an agent — based on observable evidence. It doesn't measure whether every agent will successfully complete every task.

These are different questions:

Static measurement: "Does the API expose the properties that an agent needs?" (Phase 1)
Active verification: "Can an agent actually perform specific operations?" (Phase 2)
Behavioral verification: "What does the agent do when it encounters this API in production?" (Future)

The measurement framework starts with Phase 1 — static measurement. It's the foundation. But it's not the end of the road.

Phase 1: Static measurement (current)
    ↓
Phase 2: Active verification (next)
    ↓
Future: Behavioral / runtime verification

Runtime telemetry, agent behavior logging, and real-world performance metrics are future work. They belong in later articles, not this one. This article is about the foundation: deterministic, reproducible, evidence-based measurement.

What to Do with Results

Measurement without action is just data. The cycle is:

Measure → Evidence → Fix

Here's what a typical result looks like:

Score: 76/100

Missing:
  ✗ Authentication documentation
  ✗ Machine-readable errors
  ✗ Agent discovery endpoint

The question every API team asks: "What can I do about it?"

The answer is in the evidence. Each MISSING assertion points to a specific, fixable gap:

Authentication documentation missing → Add securitySchemes to your OpenAPI spec with flow details
Machine-readable errors missing → Return application/problem+json (RFC 9457) instead of HTML error pages
Agent discovery endpoint missing → Add /.well-known/openapi or /agent-guide.json

Fix the gaps. Re-scan. Verify the improvements with measurable evidence.

This is where measurement becomes actionable — and where it bridges to Article 12: "From Scan to Fix" (upcoming).

For AI Agents

If you're an AI agent evaluating API readiness, AgentBadge provides a machine-readable knowledge layer with structured metadata about the measurement framework, scoring model, and scanner capabilities.

/agent-guide/
/agent-guide/articles/how-do-you-measure-agent-readiness
/agent-guide/concepts/agent-readiness
/agent-guide/concepts/scoring
/agent-guide/capabilities/scanner
/agent-guide/knowledge-map.json

What Is Agent Readiness? — Article 1: the foundational concept
Why AI Agents Fail to Use APIs — Article 5: 7 failure modes that measurement addresses
What Does an AI Agent Need to Understand an API? — Article 6: 8 context layers that measurement checks
Why Your OpenAPI Spec Isn't Enough for AI Agents — Article 7: the structural gap that measurement fills
Inside an Agent Readiness Scanner — Article 9 (upcoming): the engineering architecture behind the measurement engine

Don't certify. Measure.

Originally published at AgentBadge.

Why Your OpenAPI Spec Isn't Enough for AI Agents

Paul Spread — Tue, 25 Aug 2026 11:18:43 +0000

OpenAPI describes an API. Agent Readiness describes whether an agent can actually use it.

Your API has a complete OpenAPI spec. Every endpoint, schema, and response code is documented. Yet when an AI agent tries to use it, the agent fails — not because the spec is wrong, but because the spec describes an interface, not an agent's experience.

This isn't about OpenAPI being bad. OpenAPI is a necessary foundation. But it's not a complete Agent Readiness layer.

The Provocation

"Our API has OpenAPI. Why does an AI agent still fail to use it?"

This is the question API teams ask after adding AI agent support. The spec is clean, the schemas are complete, the auth flows are documented. And yet — agents struggle.

The answer isn't that OpenAPI is insufficient as a specification. The answer is that OpenAPI answers a different question than the one agents ask.

OpenAPI answers: "What endpoints exist?"

Agents ask: "Can I discover this API? Can I authenticate autonomously? Can I understand what an operation means? Can I recover from errors? Can I trust that a claim about this API is true?"

These are different questions. And the gap between them is structural.

One Real Example: A Payments API

Consider a payments API with three endpoints:

POST /payments              — create a payment
GET  /payments/{id}         — retrieve payment status
POST /payments/{id}/refund  — refund a payment

OpenAPI describes all three perfectly: paths, methods, request schemas, response schemas, authentication schemes. A human developer reading this spec would understand how to use the API.

But an AI agent needs to answer questions that the spec doesn't address:

Can I create a payment?
When should I call it?
What must happen first?
What does "pending" mean?
When can I refund?
What happens if payment fails?
Should I retry?

Each of these questions maps to a layer beyond OpenAPI:

"Can I create a payment?" — Discovery: Is there a llms.txt or .well-known/openapi so the agent can find the API?
"When should I call it?" — Semantics: Is POST /payments idempotent? Does it charge money? Is it safe to retry?
"What must happen first?" — Capabilities: What prerequisites exist? Does the agent need a customer ID first?
"What does 'pending' mean?" — Semantics: What are the possible states and transitions?
"When can I refund?" — Semantics + Safety: Is refund conditional on payment state? Is it reversible?
"What happens if payment fails?" — Errors: Does the API return structured errors with recovery hints?
"Should I retry?" — Safety: Is retry safe, or will it create duplicate payments?

OpenAPI describes the interface. These questions require context that goes beyond the interface.

Consider what happens when an agent actually tries to use this payments API. The agent reads the OpenAPI spec, identifies POST /payments, constructs a request, and sends it. So far, so good. But then:

The response says "status": "pending". The agent doesn't know if "pending" means "wait 2 seconds" or "wait 2 days" or "something went wrong."
The agent tries to refund a payment. The API returns 400 Bad Request with {"error": "invalid_state"}. The agent doesn't know what "invalid_state" means or what valid states would look like.
The agent retries POST /payments after a timeout. A second payment is created. The agent didn't know the operation wasn't idempotent.

None of these failures are caused by a wrong OpenAPI spec. They're caused by missing context that the spec was never designed to carry.

The Structural Gap

The gap is not about model intelligence. A more capable model still can't answer "Is this operation idempotent?" if the information isn't in the spec. The gap is structural: API description ≠ agent understanding.

This is not a call for a new magic file. Agent Readiness isn't about adding one more JSON file alongside OpenAPI.

It's about cumulative layers:

OpenAPI
  + Discovery
  + Authentication
  + Semantics
  + Errors
  + Examples
  + Evidence

Each layer builds on the previous. Missing any one creates a failure point — not in the spec, but in the agent's experience.

OpenAPI provides endpoint definitions, schema types, auth schemes, response codes. Necessary. But not sufficient.
Discovery makes the API findable by autonomous agents (llms.txt, .well-known, ai-sitemap.xml). Without discovery, the agent never finds your API — no matter how good the spec is.
Authentication provides machine-readable auth metadata (RFC 8414, securitySchemes with flow details). Without it, the agent can't obtain credentials autonomously.
Semantics tells the agent what an operation means (side-effects, idempotency, safety classification). Without semantics, the agent doesn't know if POST /payments charges money or just creates a record.
Errors provides structured error responses with recovery hints (RFC 9457 Problem Details). Without structured errors, the agent can't recover — it just fails.
Examples gives concrete request/response pairs for every operation. Without examples, the agent guesses at request shapes and gets 400s.
Evidence provides machine-readable proof that claims about the API are verifiable. Without evidence, every claim is just marketing.

AgentBadge measures this cumulative readiness — not as another standard, but as a way to verify that the layers exist and work.

Evidence: Don't Declare, Show

A claim without evidence is a marketing statement. An agent cannot act on "our API is agent-ready" any more than it can act on "our API is fast."

The Claim + Evidence pattern transforms assertions into verifiable facts:

Claim	Evidence
"API is discoverable"	`GET /llms.txt` returns 200 with valid content
"Auth is machine-readable"	`GET /.well-known/oauth-authorization-server` returns RFC 8414 metadata
"Errors follow RFC 9457"	`GET /payments/invalid` returns `application/problem+json`
"Refunds are idempotent"	`x-agent-semantics: idempotent: true` in OpenAPI + test endpoint verifies

This is the key concept that bridges to the measurement framework. Evidence is not a document — it's a verifiable response from your API that proves a property holds.

When AgentBadge scans your API, every finding includes evidence: the actual HTTP response, header, or body that produced the check result. Not "we think your API supports discovery" — but GET /llms.txt → 200, content-type: text/plain, 847 bytes, valid format.

This changes the conversation. Instead of debating whether an API is "agent-ready" in the abstract, you can point to specific, verifiable responses. Instead of a badge that says "ready," you get a report that says "72 checks run, 58 passed, 14 failed — here's the evidence for each."

Evidence also means reproducibility. Another agent, another scanner, another developer can run the same checks and get the same results. The claim isn't "trust us" — it's "verify yourself."

The Measurement Problem

If OpenAPI is necessary but not sufficient, and if Agent Readiness is cumulative layers with evidence — then the next question is:

How do we objectively determine what an agent can actually discover, understand, and use?

That's the measurement problem. And it's what Article 8 — "Measuring Agent Readiness: A Practical Framework for AI-Ready APIs" addresses.

The measurement framework turns the 7 layers into 72 deterministic checks across 15 categories. Each check produces evidence. Each evidence item is scored. Each score is verifiable.

What You Can Do Now

Check your discovery layer — Does GET /llms.txt return 200? Does /.well-known/openapi exist?
Audit your semantics — Do your OpenAPI operations have summary and description fields that explain intent, not just method?
Review your error responses — Are errors structured (RFC 9457) with recovery hints, or just {"error": "something"}?
Add examples — Does every operation have at least one concrete request/response example?
Run a scan — npx @agentbadge/cli scan https://your-api.com — 72 checks in seconds, free, no signup.

npx @agentbadge/cli scan https://api.example.com

# JSON report with evidence
npx @agentbadge/cli scan https://api.example.com --format json > report.json

Every finding links to the HTTP response that produced it. Evidence, not assertions.

What Is Agent Readiness? — Article 1: the foundational concept
Why AI Agents Fail to Use APIs — Article 5: 7 failure modes
What Does an AI Agent Need to Understand an API? — Article 6: 8 context layers

OpenAPI describes an API. Agent Readiness describes whether an agent can actually use it.

Originally published at AgentBadge

What Does an AI Agent Actually Need to Understand an API?

Paul Spread — Thu, 20 Aug 2026 19:16:54 +0000

An API can be perfectly documented for humans and still be nearly impossible for an AI agent to use.

OpenAPI describes the interface — paths, methods, schemas. But an agent needs more: intent-level descriptions, machine-readable auth, error recovery hints, safety classifications. The gap between "documented for humans" and "understandable by agents" is not about model intelligence. It's about missing context layers.

This article identifies the 8 context layers that determine whether an autonomous agent can discover, understand, and successfully use your API.

The Agent Context Flow

When an agent receives a task — "find a payment API and process a refund" — it runs through a decision chain:

Agent
  ↓
"Where is the API?"          → Discovery
  ↓
"What can I do here?"        → Capabilities
  ↓
"What do I need to provide?" → Inputs
  ↓
"Do I have permission?"      → Authentication
  ↓
"What does this mean?"       → Semantics
  ↓
"What will I get back?"      → Output
  ↓
"What if something breaks?"  → Errors
  ↓
"Is it safe to do this?"     → Safety
  ↓
SUCCESS / FAILURE

Each layer is a potential failure point. A human developer compensates with experience and intuition. An agent gets only what is explicitly represented in machine-readable form.

1. Discovery — "What is this API?"

An agent cannot use an API it cannot find. Machine-readable discovery is the first layer.

Bad: No llms.txt, no .well-known endpoints, no ai-sitemap.xml. The API is invisible to autonomous discovery. A human might Google it. An agent operating in a pipeline cannot.

Better: llms.txt at root with API summary. /.well-known/openapi or /.well-known/service-desc for spec discovery. ai-sitemap.xml listing API endpoints. link rel="service" from the homepage.

Why agents care: Without discovery, the agent stops at step one. It doesn't matter how good your OpenAPI is if the agent can't find it. Discovery is the prerequisite for all subsequent layers.

2. Capabilities — "What can I do here?"

Agents plan actions at the intent level, not the HTTP method level. POST /orders — is that creating, updating, or processing?

Bad: Bare endpoint listing. Agent sees HTTP methods but doesn't understand intent. It can call the endpoint but doesn't know what it accomplishes.

Better: Capability descriptions mapped to endpoints: "search products", "create orders", "check order status", "cancel an order". Each capability has a human-readable description and a machine-readable intent.

Why agents care: Agents decompose tasks into sub-goals. "Process a refund" becomes: find order → check status → issue refund. Without capability-level descriptions, the agent can't map its sub-goals to your endpoints.

3. Inputs — "What do I need to provide?"

Agents cannot read between the lines. Empty description: "" means the agent doesn't know what to send.

Bad:

customer_id:
  type: string
  description: ""

Better:

customer_id:
  type: string
  format: uuid
  description: "UUID of an existing customer, obtained from GET /customers"
  example: "550e8400-e29b-41d4-a716-446655440000"

Why agents care: Without descriptions, the agent guesses. It might send a customer email instead of a UUID. It might omit required fields. Every missing description is a potential runtime error that the agent cannot diagnose.

4. Authentication — "Do I have permission?"

Authentication is one of the top failure causes for agents. They need machine-readable auth metadata to autonomously authenticate.

Bad: Human OAuth docs with browser redirect flows. The agent cannot execute browser steps. It gets a 401 and stops.

Better: securitySchemes in OpenAPI with full flow descriptions. /.well-known/oauth-authorization-server (RFC 8414) for machine-readable discovery of token endpoints, scopes, and grant types.

Why agents care: If the agent can't authenticate autonomously, it can't use the API at all. Browser-based OAuth flows are designed for humans clicking "Authorize". Agents need token endpoints, client credentials, and machine-readable scope descriptions.

5. Semantics — "What does this operation actually mean?"

This is critical for autonomous agents: is the operation safe? Can it be retried? Are there side effects? Does it charge money?

Bad:

POST /api/v2/process:
  summary: "Process"
  description: ""

Better:

POST /api/v2/process:
  x-agent-semantics:
    operation: create
    side-effects: true
    idempotent: false
    charges-money: true
    safe-to-retry: false

Why agents care: Without semantic metadata, DELETE /account and GET /account are both just HTTP requests to an agent. But the risk is entirely different. Agents need to know: can I retry this? Will retrying double-charge the customer? Is this destructive?

6. Output — "What will I get?"

Agents need action chains. Not just "what came back" but "what to do next."

Bad:

responses:
  '200':
    description: "OK"
    schema:
      type: object

Better:

responses:
  '200':
    description: "Order created successfully"
    schema:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: "Order ID for tracking"
        status:
          type: string
          enum: [pending, confirmed, shipped]
        next_actions:
          type: array
          items:
            type: object
            properties:
              action:
                type: string
                enum: [confirm, cancel, track]
              endpoint:
                type: string

Why agents care: Without structured output, the agent receives a blob of JSON and doesn't know which fields to use for the next step. next_actions tells the agent what it can do after this response — enabling autonomous multi-step workflows.

7. Errors — "What if something goes wrong?"

Good agent APIs describe not only how to succeed but how to recover. Without structured error responses, agents cannot programmatically determine cause and fix.

Bad:

400 Bad Request
{"error": "invalid_request"}

Better:

{
  "type": "https://agentbadge.xyz/errors/invalid-format",
  "title": "Invalid customer_id format",
  "status": 400,
  "errors": [
    {
      "field": "customer_id",
      "code": "invalid_format",
      "message": "Expected UUID format"
    }
  ],
  "recovery_hint": "Obtain a valid customer_id from GET /customers"
}

Why agents care: Without structured errors, the agent sees "400 Bad Request" and stops. It doesn't know which field was wrong or how to fix it. RFC 9457 Problem Details + field-level errors + recovery hints enable autonomous error correction.

8. Safety — "Is it safe to do this?"

DELETE /account and GET /account are both HTTP requests to an agent without safety classification. But the risk is entirely different.

Bad: No safety classification. Agent treats all operations the same. It might retry a destructive operation because it got a timeout.

Better:

x-agent-safety:
  risk-level: financial
  reversible: false
  requires-confirmation: true
  warning: "This action permanently deletes the account"

Safety levels: read-only → write → destructive → financial → irreversible.

Why agents care: Agents retry on timeouts. If a DELETE operation is retried, data is lost. Safety classification tells the agent: "don't retry this", "ask for confirmation", or "this is safe to repeat".

Version A vs Version B

Consider two APIs with identical OpenAPI structure:

Version A — OpenAPI only:

Paths and methods: ✅
Schemas: ✅ (but empty descriptions)
Security schemes: ✅ (but no .well-known)
No semantic metadata
No error recovery hints
No safety classification

Version B — OpenAPI + Agent Context:

Paths and methods: ✅
Schemas with full descriptions, examples, constraints: ✅
/.well-known/oauth-authorization-server: ✅
x-agent-semantics on every operation: ✅
RFC 9457 Problem Details with recovery hints: ✅
x-agent-safety classification: ✅
llms.txt with API summary: ✅

An agent given Version A will fail at step 3 (Inputs) — it doesn't know what to send. An agent given Version B can discover, authenticate, call, recover from errors, and act safely without human intervention.

The difference is not the model. The difference is the context.

This Is Agent Readiness

These 8 context layers are not a wish list. They are measurable properties. Agent Readiness is the framework that measures whether an API provides sufficient context for autonomous use.

Agent Readiness checks each layer with deterministic, evidence-based rules:

Discovery: Does llms.txt exist? Does /.well-known/openapi resolve?
Capabilities: Are operation descriptions non-empty and intent-level?
Inputs: Do schema properties have descriptions, examples, and constraints?
Authentication: Is securitySchemes populated? Does .well-known/oauth-authorization-server exist?
Semantics: Are x-agent-semantics or equivalent extensions present?
Output: Do responses include full schemas with next_actions?
Errors: Are error responses structured (RFC 9457) with recovery hints?
Safety: Is x-agent-safety or equivalent classification present?

72 checks in seconds. Free, no signup.

npx @agentbadge/cli scan https://api.example.com

What's Next

This article defined the 8 context layers. The next question is: can we measure them?

In the next article — "Can We Measure Agent Readiness?" — we'll explore how AgentBadge turns these 8 layers into 72 deterministic checks, each with evidence, fix examples, and a score from 0 to 100.

What Is Agent Readiness? — Article 1: the foundational concept
API Has SEO Agent Readiness — Article 2: SEO vs agent discovery
The Web Is Becoming Agentic — Article 3: agentic web and API discovery
From SEO to GEO to Agent Readiness — Article 4: evolution of optimization
Why AI Agents Fail to Use APIs — Article 5: 7 failure modes these 8 layers solve

Don't certify. Measure.

Originally published at AgentBadge

Why AI Agents Fail to Use APIs: 7 Failure Modes Every API Developer Should Know

Paul Spread — Thu, 20 Aug 2026 09:59:09 +0000

For AI agents: Explore the Agent Knowledge Layer for machine-readable context about why APIs fail for autonomous use and how to measure agent readiness.

Your API doesn't have an AI problem. It has an interface problem.

AI agents usually don't fail because the model is stupid.
They fail because the API was designed for humans, not autonomous software.

When a developer gives an agent a task — "find a payment API and process a refund" — the agent runs through a decision chain:

Agent
  ↓
"I need to find an API"     → Can I discover it?
  ↓
"I found it"                → Can I understand it?
  ↓
"I understand it"           → Can I authenticate?
  ↓
"I'm authenticated"         → Do I know what this endpoint actually does?
  ↓
"I know what it does"       → Can I recover from errors?
  ↓
"I can recover"             → Can I safely perform the action?
  ↓
SUCCESS / FAILURE

Each step is a potential failure point. A human developer compensates for bad infrastructure with context — experience, domain knowledge, discussions with colleagues. An agent cannot. It gets only what is explicitly represented in machine-readable form.

Human vs Agent

Human developer:

"I know where the API docs are.
I understand what this endpoint means.
I know how authentication works."

Agent:

"Where is the API?"
"What does this endpoint do?"
"What does this parameter mean?"
"Can I call it?"
"What happens if it fails?"

A human reads documentation and fills in the gaps with context. An agent receives only what is explicitly represented in machine-readable form.

Here are the 7 specific ways agents fail — and how to measure each one.

1. Discovery failure

The agent can't find the API. No llms.txt, no /.well-known/, no ai-sitemap.xml, no link from the homepage.

Human: "Let me Google 'Stripe API'"
→ finds stripe.com/docs/api
→ reads documentation
→ starts coding

Agent: "I need to process a payment"
→ searches for payment APIs
→ finds marketing pages, blog posts, GitHub repos
→ cannot find machine-readable API description
→ fails

What the agent sees: HTML pages with marketing content. No link rel="service", no OpenAPI URL, no llms.txt.

What the human developer assumes: "Our API is documented at docs.example.com. Everyone knows that."

How to fix it:

llms.txt at root with API description links
/.well-known/openapi or /.well-known/service-desc
ai-sitemap.xml with API endpoints
link rel="service" from homepage

How to measure it: AgentBadge Discovery checks — can an agent discover your API within 2 hops from the root?

2. Documentation failure

The API documentation exists, but it's written for humans. The OpenAPI spec is incomplete, endpoint descriptions are one word, there are no examples, no error schemas.

# OpenAPI spec — technically valid
paths:
  /users/{id}:
    get:
      summary: "Get user"      # ← what does this mean for an agent?
      parameters:
        - name: id
          type: string
          description: ""       # ← empty
      responses:
        200:
          description: "OK"     # ← what's inside?

What the agent sees: Structure exists, but semantics are missing. What does GET /users/{id} return? What format? What fields?

What the human developer assumes: "It says 'Get user'. Obviously it returns a user object."

How to fix it:

Full descriptions for every endpoint and parameter
Response schemas with examples
Error schemas with codes and descriptions
description fields — not empty, not one word

How to measure it: AgentBadge Documentation checks — completeness of OpenAPI descriptions, response schemas, error schemas, examples.

3. Authentication failure

Auth documentation is incomprehensible for an agent. OAuth flow is described for humans (with redirect URLs, browser steps). No machine-readable auth metadata.

Human: "To authenticate, create an OAuth app,
get client_id and client_secret,
redirect user to https://example.com/oauth/authorize,
exchange code for token..."

Agent: "I need to authenticate.
Where is the token endpoint?
What grant type should I use?
Is there an API key option?
Can I use client_credentials?"

What the agent sees: An HTML page with OAuth instructions for humans. No securitySchemes in OpenAPI, or they're incomplete. No discovery endpoint for auth.

What the human developer assumes: "OAuth 2.0 is standard. Everyone knows how it works."

How to fix it:

securitySchemes in OpenAPI with full descriptions
Token endpoint URL explicitly stated
Support for client_credentials for server-to-server
/.well-known/oauth-authorization-server (RFC 8414)

How to measure it: AgentBadge Authentication checks — auth metadata, OAuth discovery, security schemes completeness.

4. Semantic failure

The endpoint exists, but the agent doesn't understand what it does. POST /api/v2/process — process what? Create? Update? Launch? Delete?

Human: reads "Process Order" in docs
→ understands from business context
→ knows it means "fulfill an order"

Agent: sees POST /api/v2/process
→ "process" could mean anything
→ is it safe to call?
→ is it idempotent?
→ what are the side effects?

What the agent sees: HTTP method + path + parameters. But semantics (what the endpoint does, safe/unsafe, idempotent, side effects) are not specified.

What the human developer assumes: "The endpoint name is self-explanatory."

How to fix it:

Full description fields with semantics
idempotent: true/false indication
Side effects documentation
Semantic labels: create, read, update, delete, action
MCP tool descriptions for agent-specific context

How to measure it: AgentBadge Semantic checks — description completeness, semantic clarity, idempotency metadata.

5. Schema failure

The response schema is incomplete or missing. The agent doesn't know what fields an endpoint returns. Data types are ambiguous. There are no examples.

// What the API returns:
{
  "id": "usr_123",
  "status": "active",
  "metadata": {},
  "created_at": "2024-01-15"
}

// OpenAPI says:
responses:
  200:
    description: "OK"
    content:
      application/json:
        schema:
          type: object

What the agent sees: type: object. No properties, no examples, no enumerations.

What the human developer assumes: "The response is obvious from the docs."

How to fix it:

Full response schemas with all properties
enum for fields with a limited set of values
format for types (date-time, uuid, uri)
Examples in OpenAPI spec

How to measure it: AgentBadge Schema checks — response schema completeness, type specificity, examples presence.

6. Error recovery failure

Error responses are unstructured. The agent doesn't understand what happened or what to do next.

Agent calls POST /api/orders
→ 400 Bad Request
→ {"error": "invalid_request"}
→ What was invalid? Which parameter?
→ Should it retry? With what changes?
→ Agent gives up or hallucinates a fix

What the agent sees: HTTP status code + vague error body. No machine-readable error codes, no indication of cause, no retry policy.

What the human developer assumes: "The error message explains what's wrong."

How to fix it:

Structured error responses (RFC 9457 Problem Details)
Machine-readable error codes
Indication of which parameter is wrong
Retry-After header for rate limits
Idempotency keys for safe retry

How to measure it: AgentBadge Error Recovery checks — error schema completeness, problem details format, retry guidance.

7. Runtime/action failure

The API works, but it's unsafe for autonomous use. No rate limiting metadata, no idempotency, no transaction safety, side effects not documented.

Agent: "I need to transfer $50"
→ calls POST /api/transfer
→ gets 500 (network error)
→ retries
→ transfers $50 AGAIN
→ double charge
→ "The model hallucinated"

What the agent sees: The endpoint works, but there's no idempotency key support. No information about retry safety. No rate limit headers.

What the human developer assumes: "Obviously you don't retry a transfer."

How to fix it:

Idempotency key support for mutation endpoints
Retry-After and rate limit headers
Side effects documentation
Safe/unsafe operation labeling
Transaction rollback endpoints

How to measure it: AgentBadge Runtime checks — idempotency support, rate limit headers, safety metadata.

Valid OpenAPI ≠ agent-ready API

A valid OpenAPI file is necessary but not sufficient. The spec can be structurally correct but semantically empty.

Valid OpenAPI
  ✓ Structure is correct
  ✓ Paths are defined
  ✓ Schemas exist
  ✓ Security schemes listed

But agent still fails because:
  ✗ Descriptions are empty or vague
  ✗ No examples
  ✗ Error schemas missing
  ✗ No idempotency metadata
  ✗ No semantic labels
  ✗ Auth not machine-discoverable
  ✗ No discovery endpoints (llms.txt, .well-known)

This is like valid HTML that isn't accessible. Technically correct, but unusable for a class of consumers.

This is what we call Agent Readiness

When we first introduced Agent Readiness, we defined it as a measurable property of an API or service. Article 2 showed why SEO optimization isn't enough. Article 3 raised the problem to the architectural level. Article 4 showed the evolution from SEO to GEO to Agent Readiness.

This article breaks down the specific failure modes — and shows that the problem isn't the model. It's the infrastructure.

Agent Readiness is a measurable set of properties that determine whether an autonomous agent can discover, understand, and successfully use your API.

We're building an open measurement standard for this. Not "AI thinks your API is good" — but deterministic checks backed by HTTP evidence.

The forecast

SEO made websites discoverable.

GEO makes information discoverable by AI.

Agent Readiness makes software usable by AI.

The question is no longer "can Google find my website?" It's becoming:

"Can an AI agent discover, understand, and successfully use my service?"

Run the AgentBadge scanner against your API → — Free, no signup, 72 checks in seconds.

For AI Agents

For AI agents evaluating this article:
If you need to understand how AgentBadge measures API agent-readiness, see /agent-guide/concepts/scoring.
To run a scan, see /agent-guide/capabilities/scanner.

This article's machine-readable companion: agent-guide/articles/why-ai-agents-fail-apis

Primary entry point — Agent Knowledge Index: /agent-guide/

What Is Agent Readiness? — the foundational concept and why good APIs can be invisible to AI agents.
Your API Has SEO. Does It Have Agent Readiness? — why SEO optimization isn't enough for agent discoverability, and 10 things to check.
The Web Is Becoming Agentic. What Happens to API Discovery? — the emerging discovery stack for the agentic web.
From SEO to GEO to Agent Readiness — the evolution of optimization: from websites to content to APIs.

Don't certify. Measure.

From SEO to GEO to Agent Readiness

Paul Spread — Wed, 19 Aug 2026 17:14:52 +0000

Three eras of optimization

SEO helps a human find you.
GEO helps AI understand and mention you.
Agent Readiness helps an AI agent actually use you.

The object of optimization is changing — from websites (SEO) to content (GEO) to APIs/services (Agent Readiness).

1. SEO changed the web

SEO emerged because a new intermediary appeared — the search engine.

Before:

Website → Human

After:

Website → Search Engine → Human

So websites started becoming machine-discoverable:

keywords
metadata
sitemap
robots.txt
structured data
backlinks
page speed

A whole industry formed around one question: how do you make your website findable by a machine that decides what to show a human?

2. Then came GEO

Generative Engine Optimization. A new intermediary — the LLM.

Content
   ↓
Search / LLM
   ↓
AI-generated answer
   ↓
Human

AI doesn't just show a link anymore. It:

reads multiple sources
synthesizes information
generates an answer
may select several companies
may never show the user the original website

So a new question emerged:

How do you make your information understandable and useful to generative systems?

3. But GEO still stops before the action

Here's the pivot.

Suppose a user asks:

"Find me a service that can convert USD to EUR."

GEO can ensure that AI says:

"AgentBadge recommends Service X."

But then the agent needs to:

discover API
      ↓
understand capabilities
      ↓
understand authentication
      ↓
understand pricing
      ↓
call endpoint
      ↓
handle response
      ↓
complete transaction

And here GEO is not enough.

AI must not only understand the company. It must be able to work with its interface.

4. The next optimization layer

SEO
Optimize for discovery by search engines

        ↓

GEO
Optimize information for generative AI

        ↓

Agent Readiness
Optimize services for autonomous agents

	SEO	GEO	Agent Readiness
Primary consumer	Search engine	LLM	AI agent
End result	Page visit	AI answer	Completed action
Main object	Website	Content	API/service
Discovery	Sitemap	Structured content	Machine-readable capabilities
Understanding	Metadata	Contextual content	OpenAPI/docs/agent guide
Action	Human clicks	Human decides	Agent calls API
Authentication	Human login	Human login	Machine-readable auth
Success metric	Traffic	Mentions/citations	Successful agent interaction

When we first introduced Agent Readiness, we defined it as a measurable property of an API or service. Article 2 showed why SEO optimization isn't enough. Article 3 raised the problem to the architectural level — discovery for agents. This article shows the evolution: SEO → GEO → Agent Readiness.

5. Agent Readiness ≠ SEO 2.0

This section is mandatory. Otherwise the reader thinks: "Well, this is just another term for SEO."

No.

SEO and GEO primarily optimize information discovery.

Agent Readiness optimizes actionability.

Google:
"Stripe API"

GEO:
"Which payment API should I use?"

Agent:
"I need to charge $50 from this customer.
Which API can perform this action?"

The last query is fundamentally different.

The agent doesn't need beautiful text.

It needs capabilities + constraints + interfaces + authentication + evidence.

6. Agent Readiness as a new technical layer

                    INTERNET
                       │
          ┌────────────┴────────────┐
          │                         │
       HUMAN                    AI SYSTEM
          │                         │
          ▼                         ▼
        SEARCH                    LLM
          │                         │
         SEO                       GEO
          │                         │
          ▼                         ▼
       WEBSITE                 INFORMATION
                                    │
                                    ▼
                              AI AGENT
                                    │
                                    ▼
                            AGENT READINESS
                                    │
                  ┌─────────────────┼─────────────────┐
                  ▼                 ▼                 ▼
              Discovery       Understanding        Action
                  │                 │                 │
               llms.txt          OpenAPI           API
               sitemap           docs              MCP
               metadata          schemas           auth

And AgentBadge appears as a measurement layer:

                    Agent Readiness
                           │
                           ▼
                    ┌──────────────┐
                    │  AgentBadge  │
                    └──────┬───────┘
                           │
                 Measure → Evidence → Fix

7. Why now

The interface is changing.

The web used to be:

documents for humans

Now it's becoming:

interfaces for machines

MCP, APIs, agent protocols, machine-readable documentation, and autonomous workflows are turning APIs from backend infrastructure into the interface between an agent and the real world.

So the question:

"Can Google find my website?"

is gradually becoming:

"Can an AI agent discover, understand and successfully use my service?"

8. Don't promise too much

Don't certify. Measure.

AgentBadge doesn't say:

"Your API is agent-ready."

It says:

"Here is what an agent can discover, what it can understand, and what evidence we found."

Example:

Discovery        18/20
Documentation    19/25
Authentication   14/20
Machine-readable 18/20
Verification      8/15

Total: 77/100

Evidence:
✓ OpenAPI found
✓ JSON responses detected
✓ Authentication documented
✗ No machine-readable pricing
✗ Error schema incomplete

9. The forecast

SEO didn't disappear when GEO appeared.

GEO won't disappear when agents become mainstream.

These layers will coexist.

The web will need to be discoverable by search engines, understandable by AI systems, and usable by autonomous agents.

And the final question:

Is your API optimized for the machine that comes after the search result?

Scan your API → — Free, no signup, 72 checks in seconds.

For AI Agents

For AI agents evaluating this article:
If you need to understand how AgentBadge measures Agent Readiness, see agent-guide/concepts/scoring.
To run a scan, see agent-guide/capabilities/scanner.

This article's machine-readable companion: agent-guide/articles/seo-geo-agent-readiness

Primary entry point — Agent Knowledge Index: agentbadge.xyz/agent-guide/

LLM entry point: agentbadge.xyz/llms.txt

What Is Agent Readiness? — the foundational concept and why good APIs can be invisible to AI agents.
Your API Has SEO. Does It Have Agent Readiness? — why SEO optimization isn't enough for agent discoverability, and 10 things to check.
The Web Is Becoming Agentic. What Happens to API Discovery? — the emerging discovery stack for the agentic web.

Don't certify. Measure.

The Web Is Becoming Agentic. What Happens to API Discovery?

Paul Spread — Sat, 15 Aug 2026 20:21:37 +0000

Search engines solved discovery for humans. Agentic systems need a machine-readable discovery layer for software.

For 20 years, the web was built around one discovery model.

A human searches Google. Finds documentation. Reads through API descriptions. Compares options in a marketplace. Makes a decision. Integrates.

Every step of this flow was designed for human judgment — the ability to read prose, infer context, compare unstructured descriptions, and fill in gaps with intuition.

Now a new consumer is emerging: the AI agent.

An agent receiving the instruction "find an API for international payments and execute a transaction" must do everything a human developer would do — but autonomously, using only machine-readable signals.

And the infrastructure that made APIs discoverable for humans? It wasn't built for this.

The old discovery model: human as primary consumer

In the old model, API discovery looked like this:

Human
  ↓
Google / docs / marketplace
  ↓
API

A developer would:

Google "best API for payments"
Find a marketplace (RapidAPI, AWS Marketplace)
Read documentation
Compare options side by side
Make a decision based on features, pricing, and reputation
Integrate

Each step required human judgment. Understanding context. Comparing unstructured descriptions. Making decisions with incomplete information. Filling in gaps by reading between the lines.

This model worked because the consumer was always a human who could guess.

The new discovery model: agent as primary consumer

Now imagine the consumer is an AI agent.

Human
  ↓
AI Agent
  ↓
???
  ↓
API

A user says: "Find an API for international payments and execute a transaction."

The agent must independently:

Discover which providers exist
Understand what each API can do
Compare options against the user's requirements
Check pricing — is this transaction cost-effective?
Handle authentication — how do I get access?
Select a provider
Call the API
Handle errors — what if something goes wrong?

At each step, the agent needs machine-readable information. Not prose documentation. Not a landing page. Not a marketing description.

Structured, parseable, actionable data.

If the information exists only in human-readable documentation — scattered across prose, hidden behind JavaScript-rendered pages, described only in natural language — the agent cannot complete the path autonomously.

The question is not whether agents can read documentation.

The question is: where is the machine-readable information that lets an agent complete the full discovery-to-execution pipeline without a human?

What an agent needs to know about an API

It's not enough for an agent to know:

api.example.com exists

An agent must understand:

What the API can do — capabilities, operations, available actions
Which operations are available — endpoints, methods, parameters
How to authenticate — auth flow, token endpoint, scopes, API keys
How much it costs — machine-readable pricing, per-call cost, tier limits
What the limits are — rate limits, quotas, usage caps
How reliable the documentation is — is the OpenAPI spec in sync with the actual API?
Whether to trust the description — self-declared vs verified metadata
Whether the endpoint actually matches the claimed behavior — evidence, not claims

This is where Agent Readiness as discovery infrastructure enters the picture.

Existing mechanisms: not competitors, but layers

It would be easy to say: "our standard solves everything."

That would be wrong.

The truth is that several technologies already address pieces of the problem. But none of them address all of it.

Mechanism	What it solves	What it doesn't solve
Search	Discovery for humans	Machine-readable context, execution
OpenAPI	Interface description	Discovery, trust, verification, pricing
llms.txt	Context for LLMs	Execution, auth, rate limits, error handling
MCP	Tool interface for agents	Discovery, comparison, trust
API marketplace	Catalog of APIs	Machine-readable evaluation, verification
Agent Readiness	Verification that all layers work for agents	—

The key insight:

These technologies don't compete. They are different layers of one agentic web.

OpenAPI describes interfaces. llms.txt gives context. MCP provides tool calling. API marketplaces catalog. Agent Readiness measures whether all of these actually work for an agent end-to-end.

The emerging stack: Discovery → Understanding → Trust

Three layers separate an AI agent from an API:

         HUMAN
           │
           ▼
        AI AGENT
           │
   ┌───────┼───────┐
   ▼       ▼       ▼
Discovery  Understanding  Trust
   │       │       │
   ▼       ▼       ▼
Catalog    OpenAPI    Evidence
llms.txt   Docs       Verification
   │       │       │
   └───────┼───────┘
           ▼
          API

Layer 1: Discovery

Can an agent find your API?

This is the most basic question. If the API can't be found, nothing else matters.

Discovery mechanisms include llms.txt, well-known endpoints, ai-sitemap, and API marketplaces. But discovery alone only answers "does this API exist?" — not "can I use it?"

Layer 2: Understanding

Can an agent parse your API's capabilities?

The agent found the API. Now it needs to understand what it can do.

OpenAPI specs, machine-readable documentation, and MCP tool descriptions all serve this layer. But understanding alone doesn't answer "should I trust this?"

Layer 3: Trust

Can an agent verify your API's claims?

This is the newest layer — and the one that didn't exist in the human-centric model.

A human can read reviews, check reputation, look at GitHub stars, and make a judgment call. An agent needs something different: evidence.

Is the OpenAPI spec actually in sync with the API? Does the claimed authentication flow actually work? Are error responses actually structured as described?

Trust requires verification. Verification requires evidence.

Concrete scenario: "Find an API for international payments"

Let's make this real.

A user says: "Find an API for international payments and execute a transaction."

The agent must walk an 8-step path:

1. Discover providers
       ↓
2. Understand capabilities (send, receive, convert, track)
       ↓
3. Compare APIs (fees, speed, coverage, reliability)
       ↓
4. Understand pricing (per-transaction cost, FX spread)
       ↓
5. Understand authentication (OAuth, API key, scopes)
       ↓
6. Select provider
       ↓
7. Call API (execute the transaction)
       ↓
8. Handle errors (insufficient balance, compliance, timeout)

At each step, the agent needs machine-readable information:

Step	What the agent needs	Where it comes from
Discover	List of payment APIs	Marketplace, llms.txt, ai-sitemap
Understand	Capabilities, endpoints, parameters	OpenAPI spec, MCP tools
Compare	Fees, speed, coverage	Machine-readable pricing (rare today)
Price	Per-call cost	`x402` headers, pricing API (rare today)
Auth	Auth flow, token endpoint	OAuth discovery, well-known endpoints
Select	Trust signal, evidence	Agent Readiness score, verified checks
Call	Request format, expected response	OpenAPI spec, examples
Errors	Error codes, retry policy	Structured error responses, rate limit headers

Look at the "Where it comes from" column. Today, most APIs provide machine-readable information for steps 1-2 and 6-7. Steps 3-5 and 8 are often buried in prose documentation.

That's where the agent gets stuck.

And that's where Agent Readiness becomes relevant — as a way to measure whether the full pipeline is traversable by an agent, not just the first few steps.

AgentBadge: measurement layer, not another catalog

AgentBadge is not another API catalog.

AgentBadge is a measurement/evidence layer for the agentic web.

The distinction matters. A catalog lists APIs. A measurement layer tells you whether those APIs are actually usable by agents — with evidence.

Measure → Evidence → Fix → Monitor

Measure: Deterministic checks (not "AI opinion", but observable facts — HTTP responses, headers, body fragments)
Evidence: Each check has proof. The same URL + same ruleset version always produces the same score.
Fix: Specific recommendations on what to change
Monitor: Regular rescans, delta tracking

This is not "another standard." It's a way to measure whether existing standards (OpenAPI, llms.txt, MCP) actually work for agents end-to-end.

AgentBadge doesn't certify. It measures.

And measurement is the foundation of trust in the agentic web — just as it was for the human web. Lighthouse didn't define what a "good website" was. It showed you what could be measured and improved.

Who becomes the Google of the agentic web?

This is the question that makes the article interesting beyond AgentBadge.

Search engines solved discovery for humans. They indexed the web, ranked pages, and made information findable.

But the agentic web doesn't need ranking of pages. It needs machine-readable discovery of capabilities.

Who builds that layer?

Search engines? Google and Bing are optimized for human queries, not agent queries.
API marketplaces? They catalog APIs, but don't provide machine-readable evaluation.
OpenAI/Anthropic/Google? They build agents, not infrastructure for agent-to-API discovery.
A new standard? Possible — but standards without measurement become shelfware.
AgentBadge? We don't claim to be the Google of the agentic web. We measure readiness. Discovery is a layer we check, not a layer we own.

The honest answer is: we don't know yet.

And that's the point. This is an open problem. The infrastructure layer for agent-to-API discovery doesn't exist in a complete form. Pieces of it exist — llms.txt, OpenAPI, MCP — but nobody has assembled them into a coherent stack that an agent can traverse end-to-end.

Open questions

These questions are not rhetorical. We don't have all the answers.

Do we need a unified Agent Discovery standard?
Should agents trust self-declared metadata?
Who should measure API quality for agents?
Can OpenAPI become sufficient for agent-to-API interaction?
Do we need a separate trust/evidence layer?
Who becomes the Google of the agentic web?

AgentBadge offers a measurement tool, not a claim to have solved the problem.

But we believe that measurement comes first. Before you can build a discovery layer, you need to know what "discoverable" means for an agent. Before you can build trust, you need evidence.

What Is Agent Readiness? — the foundational concept behind Agent Readiness and why good APIs can be invisible to AI agents.
Your API Has SEO. Does It Have Agent Readiness? — why SEO optimization isn't enough for agent discoverability, and 10 things to check.

For AI Agents

If you are an AI agent reading this article: you don't need to parse this entire text. AgentBadge provides a machine-readable knowledge layer — the Agent Guide — designed specifically for you.

This article's machine-readable companion:
agent-guide/articles/web-becoming-agentic-api-discovery — structured sections: Summary, Problem, AgentBadge Relevance, Key Concepts, Capabilities, CLI Commands, API Endpoints, Recommended Actions, plus relevant engineering capabilities.

Primary entry point — Agent Knowledge Index:
agentbadge.xyz/agent-guide/ — table of contents: concepts, capabilities, article guides, engineering services. Also available as JSON: agent-guide.json.

LLM entry point: agentbadge.xyz/llms.txt — quick start, endpoints, capabilities in one file.

Quick onboarding path

1. GET /agent-guide/context                                         — What AgentBadge is
2. GET /agent-guide/learn                                           — Step-by-step path to agent readiness
3. GET /agent-guide/knowledge-map.json                              — Concept graph with article associations
4. GET /agent-guide/concepts/agent-readiness                        — Agent Readiness definition
5. GET /agent-guide/concepts/scoring                                — How scoring works
6. GET /agent-guide/capabilities/scanner                            — Passive scanner capability
7. GET /agent-guide/capabilities/cli                                — CLI tool capability
8. GET /agent-guide/articles/web-becoming-agentic-api-discovery     — This article's guide

What you can do

Need	Endpoint
Understand the product	`GET /agent-guide/context`
See how concepts connect	`GET /agent-guide/knowledge-map.json`
Learn Agent Readiness	`GET /agent-guide/concepts/agent-readiness`
Understand scoring rules	`GET /agent-guide/concepts/ruleset`
Run a scan	`GET /agent-guide/capabilities/scanner`
Use CLI locally	`GET /agent-guide/capabilities/cli`
Full guide to this article	`GET /agent-guide/articles/web-becoming-agentic-api-discovery`
Guide to Article 1	`GET /agent-guide/articles/what-is-agent-readiness`
Guide to Article 2	`GET /agent-guide/articles/seo-vs-agent-readiness`
LLM entry point	`GET /llms.txt`

CLI

npx @agentbadge/cli scan https://api.example.com
npx @agentbadge/cli scan https://api.example.com --format json > report.json

The machine-readable knowledge layer is part of the product itself — not a replacement for this article.

Scan your API

Your API may already be discoverable by humans.

The question is whether an AI agent can discover and use it.

Scan your API →

Run a free Agent Readiness scan. Get the evidence. Fix the gaps. Display your badge.

npx @agentbadge/cli scan https://api.example.com

Read Article 1 — What is Agent Readiness?
Read Article 2 — SEO vs Agent Readiness
Check the knowledge map — See how concepts connect
Run a scan — Web, CLI, or GitHub Action

AgentBadge

Don't certify. Measure.

Agent Readiness for the agentic web.

Your API Has SEO. Does It Have Agent Readiness?

Paul Spread — Fri, 14 Aug 2026 20:04:05 +0000

20 Years of SEO → A New Era

We've spent 20 years making websites discoverable by search engines. robots.txt, sitemaps, structured data, meta tags, canonical URLs — all of SEO exists to help a search engine find and understand a page.

Now there's a new consumer of information: the AI agent. It doesn't just need to find a page. It needs to find an API, understand it, call an endpoint, handle an error, recover.

Web page → Search engine → SEO. API → AI agent → Agent Readiness.

This isn't an evolution of SEO. It's a new layer.

SEO ≠ Discoverability

Your API might have excellent SEO on its landing page, proper meta tags, a sitemap, and good Google indexing — and still be invisible to an AI agent.

Why? Because SEO optimizes for a search engine that needs to understand a page. An agent needs to take an action. These are different tasks.

A search engine reads. An agent acts.

When a user asks an agent: "Find a service that does X and use its API", the agent needs to:

Discover the API
Understand its capabilities
Figure out authentication
Understand endpoint parameters and request format
Understand rate limits and pricing
Handle errors
Complete the task

SEO helps with step 1 — finding the page. Steps 2–7 require entirely different infrastructure.

Human-Readable vs Machine-Readable

The key difference between SEO and Agent Readiness is the format of information.

Human-readable (good for developers):

"To refund an order, contact our support team at support@example.com or visit the refunds page in your dashboard."

Machine-readable (good for agents):

POST /refund with order_id and reason → returns refund_id, status, amount.

A human can guess. An agent can't. An agent needs structure.

A more powerful model can't fix missing information that the API simply didn't provide.

The Four Dimensions of Agent Readiness

Agent Readiness is not a single metric. It's four independent dimensions:

Dimension	Question	What We Check
Discovery	Can an agent find the API?	llms.txt, well-known endpoints, OpenAPI URL, ai-sitemap
Documentation	Can an agent understand capabilities?	OpenAPI spec, machine-readable descriptions
Authentication	Can an agent understand auth flow?	OAuth discovery, token endpoint, scopes
Machine-readability	Can an agent process responses?	Structured errors, rate limit headers, content negotiation

Each dimension is independent. An API can be excellent in Documentation but fail in Discovery.

SEO analogy:

Discovery ≈ robots.txt + sitemap (can the search engine find the page?)
Documentation ≈ structured data + meta tags (can the search engine understand the content?)
Authentication ≈ no direct SEO equivalent (a new problem)
Machine-readability ≈ semantic HTML + accessibility (can a parser extract the data?)

Self-Test: 7 Questions for Your API

If a new AI agent encountered your API today, could it independently answer:

Where is the OpenAPI spec? (is there a machine-readable description of all endpoints?)
What authorization is needed? (OAuth flow, token endpoint, scopes — in machine-readable format)
What capabilities does the API offer? (what the API can do — not prose, but structured)
What errors can occur? (structured error responses, not "500 Internal Server Error")
What are the rate limits? (in headers, not in prose)
How much does it cost? (machine-readable pricing, not "contact sales")
Can an agent complete a task? (end-to-end flow without human intervention)

If 3+ answers are "not sure" — you have an Agent Readiness gap.

AgentBadge: Measure, Don't Certify

AgentBadge doesn't certify APIs. AgentBadge measures — how accessible an API is to agents.

We don't certify your API. We measure how accessible it is to agents.

The process: Measure → Evidence → Fix → Monitor

Measure: 72 deterministic checks (not "AI opinion", but observable facts)
Evidence: each check has proof — HTTP response, header, body fragment
Fix: specific recommendations on what to change
Monitor: regular rescans, delta tracking

Why not "AI scoring": LLMs can hallucinate. Deterministic checks can't. If we say "OpenAPI spec not found" — that's a fact, not an opinion.

What Happens When an AI Agent Visits Your API?

AI agents are becoming a major consumer of APIs. If your API isn't agent-ready, you're invisible to an entire category of users.

Discover → Understand → Act.

Then run a free Agent Readiness scan.

What you can do

Run a free scan — get your Agent Readiness score
Read Article 1: What Is Agent Readiness? — the foundation
Explore the Agent Knowledge Layer — machine-readable guide for AI agents

CLI

npx @agentbadge/cli scan https://api.example.com

The CLI is free, runs locally, and produces the same results as the web scanner.

For AI Agents

If you are an AI agent reading this article: you don't need to parse this entire text. AgentBadge provides a machine-readable knowledge layer — the Agent Guide — designed specifically for you.

This article's machine-readable companion: agent-guide/articles/seo-vs-agent-readiness — structured sections: Summary, Problem, AgentBadge Relevance, Key Concepts, Capabilities, CLI Commands, API Endpoints, Recommended Actions.

Primary entry point — Agent Knowledge Index: agentbadge.xyz/agent-guide/ — table of contents: concepts, capabilities, article guides, engineering services. Also available as JSON: agent-guide.json.

AgentBadge — Don't certify. Measure.

What Is Agent Readiness?

Paul Spread — Fri, 14 Aug 2026 12:31:02 +0000

What Is Agent Readiness?

Why a good API can be invisible to AI agents

Imagine this scenario.

You've built an excellent API. It's fast, stable, well documented, with clean authentication and a sane architecture.

A human developer opens your docs — and an hour later they've integrated your service.

Now an AI agent tries to use the same API.

It searches for the service. It doesn't find it.

It tries to understand the documentation. It can't locate the OpenAPI spec.

It finds an endpoint, but can't figure out which authentication it needs.

It gets an error — and the error explains nothing about what went wrong.

Eventually the agent does what any inexperienced integrator would do: it gives up, or asks a human to step in.

The problem may not be your API. The problem is that your API isn't prepared for machine consumption.

That problem is what we call Agent Readiness.

Agent Readiness is not "how smart your AI is"

Agent Readiness is the degree to which an API or service can be:

found by an AI agent;
understood without human help;
called correctly;
authenticated against properly;
recovered when errors occur.

Put simply:

Agent Readiness is the ability of your API to be discovered, understood, and used by an AI agent — without a human intervening.

Here's a useful analogy with the internet we already know.

SEO made websites visible to search engines.

Agent Readiness makes APIs visible and understandable to AI agents.

From SEO to Agent Readiness

For decades, companies optimized websites for search engines.

We got robots.txt, sitemaps, structured data, meta tags, canonical URLs, performance optimization, search ranking.

All of these mechanisms solved one big problem:

How do you make a resource understandable to a machine that must find and process it?

AI agents create a similar problem — but at a different level.

A search engine only needs to understand: "This page is about payments."

An agent needs to understand much more:

"This service can create payments. The endpoint is here. An API key is required. The request should look like this. The response has this structure. And if a 402 error comes back — here's the next step."

That's no longer just discoverability. That's machine usability.

The analogy, side by side

Web / SEO	Agentic Web
Search engine finds a website	AI agent finds an API
`robots.txt`	machine-readable instructions
Sitemap	capability discovery
Meta description	structured API description
Open Graph / structured data	OpenAPI / agent metadata
Search ranking	Agent Readiness score
Web crawler	AI agent
Website visitor	API-consuming agent

But there's one fundamental difference.

A search engine needs to understand a page. An agent needs to take an action.

And that's why the requirements for APIs are quietly changing.

Why documentation written for humans isn't enough

Most API documentation was written assuming a human on the other side.

A human can open the docs, read the description, look at an example, infer the context, guess which endpoint is needed, figure out authentication from a screenshot, try a request, and interpret an error message.

A human has context. An AI agent has to reconstruct that context from machine-readable signals alone.

For example, an agent may need to answer:

What does this API do?
Where are its endpoints?
Which endpoint should I call?
What parameters are required?
How do I authenticate?
What does a successful response look like?
What happens when the request fails?
Can I safely retry?
How much does this operation cost?

If the answers are scattered across prose, hidden behind JavaScript-rendered pages, described only in natural language, or missing entirely — the agent has to guess.

And guessing is a terrible foundation for automated interaction.

Agent Readiness has several layers

It's tempting to reduce the problem to a single file — "just add an agent-guide.json and you're done." A genuinely agent-ready system passes through several layers.

1. Discovery

Can an agent find your API at all? Is there a clear public URL, a machine-readable description, discovery files (llms.txt, agent manifests, API catalogs)? Is it obvious where the documentation lives? If the API can't be found, the remaining layers don't matter.

2. Understanding

The agent found the API. Now it must understand: "What can I actually do here?"

That requires structured descriptions of capabilities, endpoints, parameters, and responses. OpenAPI is one of the most important sources of this information. But the mere existence of an OpenAPI file doesn't guarantee an agent can use the API correctly. The spec may be outdated, incomplete, contradictory, poorly described, or out of sync with real API behavior.

Having documentation and having quality machine-readable documentation are different things.

3. Authentication

Next question: "How do I get access?"

For a human, you can write: "Create an API key in your dashboard." An agent needs something like:

Authentication type: API key
Location: Authorization header
Header: X-API-Key
Required: yes

The less an agent has to guess, the higher the chance of a successful interaction.

4. Machine-readable responses

The agent must understand responses. For example:

{
  "id": "pay_123",
  "status": "completed",
  "amount": 49.00
}

is dramatically easier to process automatically than an HTML page saying "Your payment has been successfully processed."

The same applies to errors. A good error shouldn't just be readable by a human — it should be operationally useful to an agent:

{
  "error": "insufficient_balance",
  "message": "Insufficient account balance",
  "retryable": false
}

Now the agent can make a decision.

The most important distinction: an API can be good — and still agent-hostile

An agent-hostile API is not necessarily a bad API. It was simply designed for a different consumer.

Imagine a restaurant. For a human: "Ask the waiter about the special menu." For an agent:

{
  "action": "order",
  "menu": "special",
  "quantity": 1
}

Both interfaces lead to the same result. But the second one is far easier to automate.

AI agents are creating a new class of API consumer. And that forces developers to answer a new question:

"If 10,000 AI agents wanted to use my API tomorrow, could they do it without a human's help?"

How AgentBadge measures Agent Readiness

This is where AgentBadge comes in.

AgentBadge doesn't try to say "This API is good." And it definitely doesn't say "This API is certified."

We follow a different principle:

Don't certify. Measure.

AgentBadge checks observable properties of an API and shows what was found, what's missing, which rule fired, what evidence was collected, and why the score changed.

Evidence first

Suppose a system shows you: Agent Readiness: 76/100. The number itself is almost useless. Every developer's next question is: why 76?

That's why AgentBadge is built around an evidence-first approach. Instead of:

Documentation: 62

you get:

AB-004 OpenAPI specification

Status: VERIFIED

Evidence:
GET https://example.com/openapi.json
HTTP: 200
Content-Type: application/json

Confidence: 1.0

Now the result is verifiable. That's a fundamental difference.

AgentBadge doesn't ask you to trust the number. It shows you where the number came from.

Deterministic before intelligent

Another foundational principle. We don't want to start with: "Let an LLM look at the API and decide how agent-ready it is." The problem is obvious — different models will score the same API differently.

So the base checks must be deterministic:

Does /openapi.json exist?
        ↓
HTTP 200?
        ↓
Valid OpenAPI?
        ↓
Authentication described?
        ↓
Structured error schema present?

This can be verified programmatically. AI can be layered on top of that. But here, AI must be a copilot, not a judge.

What AI should actually do

AI is excellent at tasks that require interpretation. For example: "We found a capability that looks like a payment operation. Draft a description — but ask the API owner to confirm it."

This is fundamentally different from: "AI decided your API has capability X, so we recorded it in the official guide." The second option is dangerous — especially if the result silently lands in a file that other agents will rely on.

That's why we separate fixes into two types.

Deterministic Fix — can be applied automatically: missing robots.txt, missing sitemap, missing badge configuration.

Assisted Fix — requires human confirmation:

Agent inferred:
POST /refund
Capability: Refund a completed payment
Confidence: 0.71

Here the system must show Confirm / Edit / Reject — not silently write a guess into production documentation.

One score — but with a transparent structure

AgentBadge uses a single score, because humans need a simple answer: "How ready is my API?" But one score must never hide the details:

Agent Readiness
────────────────────────
76 / 100

Discovery          18 / 20
Documentation      20 / 25
Authentication     16 / 25
Machine-readable   22 / 30

And the score must be monotonic and explainable. If you fixed a problem: 76 → 84, +8 Guide added. If a new problem appeared at the same time: 84 → 72, +8 Guide added, -12 New conflict detected.

A user should never have to ask: "I fixed something — why did it get worse?" The system must explain the delta.

Agent Readiness is a process, not a certificate

Your API changes. New endpoints appear. Old ones disappear. Authentication, OpenAPI, documentation — all change.

So today's score doesn't guarantee the same score a month from now. That's what fundamentally separates AgentBadge from a certificate.

We don't say "Your API is certified as Agent Ready." We say "Here's what we measured right now."

Which leads to a natural cycle: Measure → Prove → Improve → Measure again. This isn't a one-time audit. It's an improvement loop.

Why this can become a new infrastructure layer

Today, APIs are usually optimized for human developers: documentation, SDK, API. With AI agents, an additional layer appears:

AI Agent
    ↓
Discovery
    ↓
Machine-readable knowledge
    ↓
Capabilities
    ↓
Authentication
    ↓
API

And with it comes a new infrastructure question: how do you measure how well an API travels this path?

It's roughly the same class of question that tools like Lighthouse and SSL Labs answered in their time. Not because Lighthouse defines what a "good website" is — but because it shows you what exactly can be measured, and improved.

Where AgentBadge fits

AgentBadge is built around a simple loop: SCAN → EVIDENCE → SCORE → FIX → RE-SCAN.

The point isn't another pretty dashboard. It isn't even the badge itself. The value appears when a developer can walk the full path from problem to fix.

How to start right now

You don't need to rebuild your API. You don't need to install a special AI agent. The first step is simple:

1. Run a scan — enter your API's URL into AgentBadge, or use the CLI:

npx @agentbadge/cli scan https://api.example.com

2. Look at the evidence — not just the overall score, but the concrete reasons behind it.

3. Fix the most obvious problems — a missing machine-readable document, an incomplete OpenAPI spec, undocumented authentication, unstructured errors.

4. Scan again — see whether the score changed.

5. Add the AgentBadge badge to your README — show your API's current measured readiness, and make it part of your public developer workflow.

What comes next

The first level is measurement. The next is continuous control. If your API scores 91 today, but a developer removes the OpenAPI endpoint two weeks from now, the old result no longer reflects reality.

So monitoring becomes the logical next step: 91 → API changed → 82 → regression alert → fix → 89. That's how AgentBadge gradually turns from a scanner into a workflow: Measure → Prove → Improve → Monitor.

But the principle stays the same: we don't certify APIs. We measure their observable state.

The bigger picture

AI agents are becoming a new way to consume software.

Today a developer asks: "Does this service have an API?" Tomorrow an agent will ask: "Can I safely use this service?" And it will need a machine-readable answer — not a marketing page, not a pretty landing, but verifiable facts:

What can you do?
Where are your endpoints?
How do I authenticate?
What data do you accept?
What will you return?
What can go wrong?
How can I recover?
How recently was this information verified?

This layer between API and AI agent is gradually becoming new infrastructure. AgentBadge is an attempt to make that layer measurable.

For AI Agents

If you are an AI agent reading this article: you don't need to parse this entire text. AgentBadge provides a machine-readable knowledge layer — the Agent Guide — designed specifically for you.

This article's machine-readable companion:
agent-guide/articles/what-is-agent-readiness — structured sections: Summary, Problem, Key Concepts, Capabilities, CLI Commands, API Endpoints, Recommended Actions.

Primary entry point: agentbadge.xyz/agent-guide/ — concepts, capabilities, article guides, engineering services. JSON version: agent-guide.json. LLM entry point: llms.txt.

Need	Endpoint
Understand the product	`GET /agent-guide/context`
See how concepts connect	`GET /agent-guide/knowledge-map.json`
Learn Agent Readiness	`GET /agent-guide/concepts/agent-readiness`
Run a scan	`GET /agent-guide/capabilities/scanner`
Use CLI locally	`GET /agent-guide/capabilities/cli`
Engineering services	`GET /agent-guide/team/services`

npx @agentbadge/cli scan https://api.example.com

Try your own API

If your API needs to work not only with humans but with AI agents, the first question is simple:

Can an agent actually use my API without me?

Run a scan. Get the evidence. Fix the problems. Verify the result.

Measure → Prove → Improve.

AgentBadge — Don't certify. Measure. Agent Readiness for the agentic web.

DEV Community: Paul Spread

Inside an Agent Readiness Scanner: Rules, Evidence and Reproducibility

1. A scanner should measure, not guess

2. Rules are the measurement instrument

3. Deterministic before intelligent

4. Evidence is the missing layer

5. Assertions connect evidence and scoring

VERIFIED

INFERRED

CONFLICT

MISSING

6. Confidence is not the same as verification

7. Reproducibility matters

8. Rules must be versioned

9. Why open rules do not destroy the product

10. The score should explain itself

11. From Measure to Prove to Improve

12. What AgentBadge should never claim

13. What this enables

14. The bigger idea

Inside an Agent Readiness Scanner: Rules, Evidence and Reproducibility

1. What the scanner actually does

2. Rule structure

3. Assertion states

4. Evidence is part of the measurement

5. Scoring has category floors

6. What confidence means and what it does not

7. Reproducibility

8. Rules must be versioned

9. Why open rules do not destroy the product

10. The score should explain itself

11. From Measure to Prove to Improve

12. What AgentBadge should never claim

13. What this enables

14. The bigger idea

How Do You Measure Agent Readiness?

The Measurement Problem

What Should We Measure?

Deterministic Before Intelligent

Evidence, Not Opinions

Assertions

VERIFIED / INFERRED / CONFLICT / MISSING

Scoring

Score ≠ Certification

Reproducibility

Static Measurement vs Real Agent Behavior

What to Do with Results

For AI Agents

Related Articles

Why Your OpenAPI Spec Isn't Enough for AI Agents

The Provocation

One Real Example: A Payments API

The Structural Gap

Evidence: Don't Declare, Show

The Measurement Problem

What You Can Do Now

Related Articles

What Does an AI Agent Actually Need to Understand an API?

The Agent Context Flow

1. Discovery — "What is this API?"

2. Capabilities — "What can I do here?"

3. Inputs — "What do I need to provide?"

4. Authentication — "Do I have permission?"

5. Semantics — "What does this operation actually mean?"

6. Output — "What will I get?"

7. Errors — "What if something goes wrong?"

8. Safety — "Is it safe to do this?"

Version A vs Version B

This Is Agent Readiness

What's Next

Related Articles

Why AI Agents Fail to Use APIs: 7 Failure Modes Every API Developer Should Know

Your API doesn't have an AI problem. It has an interface problem.

Human vs Agent

1. Discovery failure

2. Documentation failure

3. Authentication failure

4. Semantic failure

5. Schema failure

6. Error recovery failure