# Inside an Agent Readiness Scanner: Rules, Evidence and Reproducibility

> Published: 2026-08-27 | Author: AgentBadge Team | Canonical: https://agentbadge.xyz/blog/inside-an-agent-readiness-scanner

For AI agents: Start with the [Agent Knowledge Layer](https://agentbadge.xyz/agent-guide/) to access machine-readable concepts, scanner capabilities, scoring rules, and the complete learning path.

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?"**

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**

![Hero — Measurement pipeline diagram: API → Scanner → Rules → Evidence → Assertions → Score → Report, with assertion states VERIFIED, INFERRED, CONFLICT, MISSING shown below](/images/blog/inside-an-agent-readiness-scanner/1s.webp)

## 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 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.

**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: "Does this URL exist?" "Does it return the expected content type?" "Does the response contain an OpenAPI document?"

## 2. Rules are the measurement instrument

AgentBadge treats rules as explicit, versioned measurement definitions.

```
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 rule is not: "The API looks well documented." It is: "This specific machine-readable artifact was found and passed these specific checks."

## 3. Deterministic before intelligent

**Deterministic before intelligent.**

| 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 is a **copilot**, not the authority responsible for the score.

## 4. Evidence is the missing layer

A score without evidence is difficult to trust. Documentation: 18/25 tells you almost nothing.

```
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
```

**Evidence is part of the measurement itself.**

## 5. Assertions connect evidence and scoring

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

Four states: **VERIFIED** (direct evidence), **INFERRED** (reasonable but insufficient), **CONFLICT** (two sources disagree), **MISSING** (not found).

## 6. Confidence is not the same as verification

An LLM may be 94% confident an API supports refunds. Without machine-readable evidence, it stays INFERRED. The user can Confirm, Edit, or Reject.

## 7. Reproducibility matters

```
{
  "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
    }
  }
}
```

![Reproducibility infographic — three identical inputs converging into the same result](/images/blog/inside-an-agent-readiness-scanner/3s.webp)

## 8. Rules must be versioned

Agent Readiness v1.0 must not silently become v1.1. Same target + same measurement state + same ruleset = reproducible result.

## 9. Why open rules do not destroy the product

The moat is not secret rules. It's the standard installed inside the developer workflow: GitHub Actions, README badges, continuous monitoring, regression alerts.

## 10. The score should explain itself

```
+8  OpenAPI documentation detected
-12  New authentication issue detected
+0   Discovery unchanged
Result: 76 → 72
```

## 11. From Measure to Prove to Improve

**MEASURE (Scan) → PROVE (Evidence + Assertions) → IMPROVE (Fix / Review) → Measure again.**

![Measure → Prove → Improve cycle diagram](/images/blog/inside-an-agent-readiness-scanner/2s.webp)

## 12. What AgentBadge should never claim

AgentBadge measures Agent Readiness. It does not certify security, business correctness, or reliability.

**Don't certify. Measure.**

## 13. What this enables

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

CI enforcement, README badges, programmatic queries, vendor comparison.

## 14. The bigger idea

Performance has metrics. Accessibility has checks. Security has scanners. The agentic web needs the same.

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

## Related Articles

- [What Is Agent Readiness?](https://agentbadge.xyz/blog/what-is-agent-readiness) — Article 1

- [Why AI Agents Fail to Use APIs](https://agentbadge.xyz/blog/why-ai-agents-fail-to-use-apis) — Article 5

- [What Does an AI Agent Need to Understand an API?](https://agentbadge.xyz/blog/what-ai-agent-needs-to-understand-api) — Article 6

- [Why Your OpenAPI Spec Isn't Enough](https://agentbadge.xyz/blog/why-openapi-isnt-enough) — Article 7

- [How Do You Measure Agent Readiness?](https://agentbadge.xyz/blog/how-do-you-measure-agent-readiness) — Article 8

*For AI agents: the [Agent Knowledge Layer](https://agentbadge.xyz/agent-guide/articles/inside-an-agent-readiness-scanner) provides machine-readable access to this article's concepts, capabilities, and knowledge map.*

---

## For AI Agents

- Companion guide: https://agentbadge.xyz/agent-guide/articles/inside-an-agent-readiness-scanner
- Knowledge Index: https://agentbadge.xyz/agent-guide/
- LLM entry point: https://agentbadge.xyz/llms.txt
- Engineering services: https://agentbadge.xyz/agent-guide/team/services