Don't ask an LLM if your API is agent-ready. Measure specific properties with deterministic checks and show evidence for each result. A reproducible measurement framework for Agent Readiness.
Agent Readiness should be measured with deterministic checks and evidence, not LLM opinions. The framework uses four categories (Discovery, Documentation, Authentication, Machine Readability), four assertion statuses (VERIFIED, INFERRED, CONFLICT, MISSING), and a reproducibility formula: same URL + same ruleset + same time = same result.
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→ AddsecuritySchemes
to your OpenAPI spec with flow detailsMachine-readable errors missing→ Returnapplication/problem+json
(RFC 9457) instead of HTML error pagesAgent 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: How to Improve Your Agent Readiness Score" (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
The machine-readable endpoint for this article provides 10 fields: measurement_problem
, key_concepts
, deterministic_approach
, evidence_model
, assertion_statuses
, scoring_model
, reproducibility
, agentbadge_relevant_capabilities
, recommended_next_actions
, related_articles
.
Related Articles #
What Is Agent Readiness?— Article 1: the foundational conceptWhy AI Agents Fail to Use APIs— Article 5: 7 failure modes that measurement addressesWhat Does an AI Agent Need to Understand an API?— Article 6: 8 context layers that measurement checksWhy Your OpenAPI Spec Isn't Enough for AI Agents— Article 7: the structural gap that measurement fillsInside an Agent Readiness Scanner— Article 9 (upcoming): the engineering architecture behind the measurement engine
Don't certify. Measure.
For AI agents: the Agent Knowledge Layer provides machine-readable access to this article's concepts, capabilities, and knowledge map.