# Example agent-readability report

> Northstar Metrics API · fictional B2B usage-analytics product · illustrative report

**Disclosure:** Northstar Metrics API, its URLs and every response below are
fictional. The evidence is constructed to show the format, depth and judgement
of the paid deliverable without exposing a customer. This is not a live audit or
a claimed customer result.

- Human report: https://kc-it.pl/services/agent-readability-example
- Structured report: https://kc-it.pl/services/agent-readability-example.json
- Service and scope: https://kc-it.pl/services/agent-readability

## Decision summary

**Current: D · 65/100 · 12 of 20 checks.**

**Expected after the four recommended changes: A · 93/100 · 16 of 20.**
That is an expected result from the same public checklist, not a forecast of
rankings, model mentions, recommendations, citations or sales.

The site already communicates its product purpose over HTTPS, permits the
crawlers it wants, publishes a sitemap and compact llms.txt, and exposes an
honest informational A2A card. The commercial page does not express its product
and price as typed facts, does not advertise its JSON or Markdown twins, lacks a
declared social image, and has no full-text llms companion.

The remaining four low-weight gaps are intentionally **not** part of the
recommended work. Northstar does not expose an MCP server or agent task, and the
sample assumes no stable OpenAPI catalog or response-signing operation. Adding
those documents just to reach 100 would make the site less truthful.

## Scope and method

- Subject: `https://northstar-metrics.example` (reserved `.example` domain)
- Pages represented: `/` and `/pricing`
- Audit date: 2026-08-07
- Check set: v2, 20 weighted checks
- Method represented: public GET requests, HTML head inspection, discovery-file
  validation, crawler-policy parsing and `Accept: text/markdown` negotiation
- Score: `round(79 earned weight / 122 total weight × 100) = 65`

## Priority queue

### P1 · State the product and offer as typed facts · weight 15

**Finding:** no schema.org JSON-LD was found on the commercial page.

**Evidence:** `GET /pricing` returns visible copy for a Pro plan at `$79/month`,
but the HTML contains no `script[type="application/ld+json"]`.

**Why it matters:** an agent can read the prose, but must infer that Northstar is
a software product and that `$79/month` is a real offer rather than a stray
number.

**Fix:** generate `SoftwareApplication` and `Offer` JSON-LD from the same product
and price source that renders the visible card.

**Needed from the owner:** confirm the billing period, currency, availability and
whether the visible price excludes tax. The implementation-ready block is
finalized only after those facts are confirmed.

### P1 · Advertise the machine-readable twins · weight 8

**Finding:** the HTML head contains no JSON or Markdown alternate.

**Evidence:** canonical and stylesheet links are present; no
`rel="alternate"` has an `application/json` or `text/markdown` media type.

**Fix:**

```html
<link rel="alternate" type="application/json"
      href="https://northstar-metrics.example/product.json">
<link rel="alternate" type="text/markdown"
      href="https://northstar-metrics.example/product.md">
```

Send the equivalent `Link` response header and `Vary: Accept` where content
negotiation is used.

### P1 · Complete the share-card contract · weight 7

**Finding:** `og:title` and `og:description` exist; `og:image` does not.

**Why it matters:** cards assembled by search and assistant interfaces have no
declared visual and may choose an unrelated asset.

**Fix:** publish one stable 1200×630 product card and add `og:image`, its width,
height and descriptive alt text.

**Needed from the owner:** approve the product-card visual or provide the
existing brand asset that should be used.

### P2 · Add the full-text llms companion · weight 5

**Evidence:** `GET /llms.txt` returns 200 with an H1 and summary;
`GET /llms-full.txt` returns 404.

**Why it matters:** an agent can discover the right pages, but needs several
additional fetches to answer product, price, authentication and limits
questions.

**Fix:** generate `/llms-full.txt` from approved source content. Inline the
concise product, pricing, authentication and limits sections; do not blindly
concatenate private, duplicate or stale documentation.

**Needed from the owner:** confirm which documentation pages are safe and
current enough to reproduce in full.

## Full check table

| check | weight | result | evidence / disposition |
|---|---:|---|---|
| llms.txt published | 15 | pass | 200; H1 is `Northstar Metrics API` |
| llms.txt title and summary | 5 | pass | blockquote summary follows H1 |
| llms-full.txt published | 5 | **fail · P2** | 404; generate from approved docs |
| robots.txt published | 5 | pass | 200 text/plain |
| AI crawlers not blocked | 10 | pass | no audited AI agent is disallowed |
| sitemap.xml published | 8 | pass | 200 XML; declared in robots.txt |
| schema.org JSON-LD | 15 | **fail · P1** | no schema.org node on `/pricing` |
| title and description | 7 | pass | both present and product-specific |
| Open Graph metadata | 7 | **fail · P1** | image missing |
| canonical URL | 5 | pass | canonical uses audited HTTPS URL |
| machine-readable alternates | 8 | **fail · P1** | no JSON or Markdown alternate |
| agent card | 10 | pass | current path; explicitly informational |
| HTTPS | 5 | pass | page and canonical use HTTPS |
| Content Signals | 3 | pass | `search=yes, ai-input=yes, ai-train=no` |
| current A2A card path | 3 | pass | `/.well-known/agent-card.json` |
| Markdown negotiation | 3 | pass | `Accept: text/markdown` returns Markdown |
| MCP server card | 2 | defer | no MCP server; do not invent one |
| RFC 9727 API catalog | 2 | defer | add only with stable OpenAPI ownership |
| Agent Skills index | 2 | not applicable | no agent task exists |
| Web Bot Auth directory | 2 | defer | needs signing-key storage and rotation |

## Implementation order

1. Owner confirms the four commercial facts and approved source pages.
2. Add JSON-LD and machine alternates at the shared commercial template.
3. Publish the Open Graph asset and metadata.
4. Generate `llms-full.txt` from the approved source content.
5. Deploy, fetch every artifact from production, and run the same v2 audit.

The expected score after those changes is 93/100. A perfect score is not the
target: the remaining points represent capabilities this fictional product does
not currently have.

## Boundary

This report evaluates technical discoverability and parseability. It cannot
guarantee a search ranking, model mention, recommendation, citation or
conversion. CDN-managed crawler rules, authentication walls and dashboard-only
settings require owner access and are listed separately in a real engagement.

## Request the real report

The fixed-scope report is $49 for one public origin and one representative
commercial page, delivered as Markdown and JSON within one business day after
fit and payment are confirmed:

mailto:110kc3@gmail.com?subject=Request%20the%20%2449%20agent-readability%20report&body=Site%20URL%3A%0A