{ "schema_version": "1.0", "document_type": "example_agent_readability_report", "title": "Example agent-readability report — Northstar Metrics API", "url": "https://kc-it.pl/services/agent-readability-example", "alternate_formats": { "html": "https://kc-it.pl/services/agent-readability-example", "markdown": "https://kc-it.pl/services/agent-readability-example.md", "json": "https://kc-it.pl/services/agent-readability-example.json" }, "disclosure": { "fictional": true, "live_audit": false, "customer_work": false, "statement": "Northstar Metrics API and all request evidence in this report are fictional. They are constructed to demonstrate the format, depth and judgement of the paid deliverable without exposing a customer." }, "subject": { "name": "Northstar Metrics API", "url": "https://northstar-metrics.example", "category": "Fictional B2B usage-analytics API", "audited_pages": [ "https://northstar-metrics.example/", "https://northstar-metrics.example/pricing" ] }, "audit": { "audited_at": "2026-08-07T10:00:00Z", "check_set": "v2", "checks": 20, "total_weight": 122, "earned_weight": 79, "score": 65, "letter": "D", "grade": "partially readable", "passed": 12, "expected_after_recommended_work": { "earned_weight": 114, "score": 93, "letter": "A", "passed": 16, "qualification": "Expected score from the same public checklist after the four recommended changes. It is not a visibility, ranking, mention or citation forecast." } }, "decision_summary": [ "The product purpose, HTTPS posture, crawler policy and basic discovery files are already legible.", "The commercial page does not state its product and offer as typed facts: schema.org JSON-LD is absent.", "The HTML does not advertise JSON or Markdown twins, so a machine must infer where structured facts live.", "The social-card metadata is incomplete and llms-full.txt is missing.", "Do not add an MCP card, API catalog, Agent Skills index or response-signing directory unless Northstar actually exposes those capabilities." ], "recommended_work": [ { "priority": "P1", "check_id": "json_ld", "weight": 15, "finding": "No schema.org JSON-LD was found on the commercial page.", "evidence": "GET /pricing returned HTML with a visible Pro offer, but no script[type=\"application/ld+json\"].", "impact": "Agents can read the prose, but must infer that Northstar is a software product and that $79/month is an offer rather than a stray number.", "fix": "Add SoftwareApplication and Offer JSON-LD generated from the same product and price data as the visible card.", "owner_input": "Confirm the billing period, currency, availability and whether the $79 price excludes tax." }, { "priority": "P1", "check_id": "machine_alternates", "weight": 8, "finding": "No machine-readable alternate links are advertised in the page head.", "evidence": "The response head contains canonical and stylesheet links, but no rel=\"alternate\" with application/json or text/markdown.", "impact": "A caller has to know or guess the structured URL instead of discovering it from the page being evaluated.", "fix": "Add JSON and Markdown alternate links to the root commercial template and send the equivalent Link response header.", "owner_input": "None if the proposed /product.json and /product.md URLs are acceptable." }, { "priority": "P1", "check_id": "open_graph", "weight": 7, "finding": "Open Graph metadata is incomplete.", "evidence": "og:title and og:description are present; og:image is absent.", "impact": "Cards assembled by search and assistant interfaces have no declared visual and may choose an unrelated asset.", "fix": "Publish a stable 1200×630 product card and add og:image, its dimensions and alt text.", "owner_input": "Approve the product-card visual or provide an existing brand asset." }, { "priority": "P2", "check_id": "llms_full_txt", "weight": 5, "finding": "The compact llms.txt exists, but its full-text companion does not.", "evidence": "GET /llms.txt returned 200 with an H1 and summary; GET /llms-full.txt returned 404.", "impact": "An agent can discover the right pages but needs several additional fetches to answer product, price and integration questions.", "fix": "Generate /llms-full.txt from the same source content, inlining the concise product, pricing, authentication and limits sections.", "owner_input": "Confirm which documentation pages are safe to reproduce in full." } ], "not_recommended": [ { "check_ids": ["mcp_server_card"], "reason": "Northstar does not expose an MCP server. Publishing a card would invent a callable capability." }, { "check_ids": ["api_catalog"], "reason": "The fictional sample assumes no stable OpenAPI description or public API catalog yet. Add RFC 9727 discovery only when those resources exist." }, { "check_ids": ["agent_skills"], "reason": "Northstar accepts no agent task protocol. A skills index would be theatre until a real skill or ordering flow exists." }, { "check_ids": ["web_bot_auth"], "reason": "Response signing requires key generation, secret storage and rotation ownership. Do not publish an empty directory merely for two points." } ], "checks": [ {"id":"llms_txt","label":"llms.txt published","weight":15,"pass":true,"evidence":"GET /llms.txt → 200 text/plain; first line is # Northstar Metrics API."}, {"id":"llms_txt_summary","label":"llms.txt has a title and summary","weight":5,"pass":true,"evidence":"A blockquote summary follows the H1."}, {"id":"llms_full_txt","label":"llms-full.txt published","weight":5,"pass":false,"priority":"P2","evidence":"GET /llms-full.txt → 404.","remediation":"Generate a full-text companion from approved product documentation."}, {"id":"robots_txt","label":"robots.txt published","weight":5,"pass":true,"evidence":"GET /robots.txt → 200 text/plain."}, {"id":"ai_crawlers_allowed","label":"AI crawlers not blocked","weight":10,"pass":true,"evidence":"No audited AI user-agent is disallowed."}, {"id":"sitemap","label":"sitemap.xml published","weight":8,"pass":true,"evidence":"GET /sitemap.xml → 200 application/xml; robots.txt declares its URL."}, {"id":"json_ld","label":"schema.org JSON-LD on the page","weight":15,"pass":false,"priority":"P1","evidence":"No schema.org JSON-LD node found on /pricing.","remediation":"Add SoftwareApplication and Offer nodes sourced from visible facts."}, {"id":"title_and_description","label":"title and meta description","weight":7,"pass":true,"evidence":"Both are present and specific to the product."}, {"id":"open_graph","label":"Open Graph tags","weight":7,"pass":false,"priority":"P1","evidence":"og:title yes; og:description yes; og:image no.","remediation":"Add a stable 1200×630 product image and complete its metadata."}, {"id":"canonical","label":"canonical URL declared","weight":5,"pass":true,"evidence":"Canonical resolves to the audited HTTPS page."}, {"id":"machine_alternates","label":"machine-readable alternates advertised","weight":8,"pass":false,"priority":"P1","evidence":"No JSON or Markdown rel=alternate link found.","remediation":"Advertise the proposed /product.json and /product.md representations."}, {"id":"agent_card","label":"agent card at the current A2A path","weight":10,"pass":true,"evidence":"GET /.well-known/agent-card.json → 200 application/json; the card explicitly says it is informational."}, {"id":"https","label":"served over HTTPS","weight":5,"pass":true,"evidence":"The audited URL and canonical both use HTTPS."}, {"id":"content_signals","label":"Content Signals declared in robots.txt","weight":3,"pass":true,"evidence":"Content-Signal: search=yes, ai-input=yes, ai-train=no."}, {"id":"agent_card_current_path","label":"A2A card at the 1.0 path","weight":3,"pass":true,"evidence":"The card is served at /.well-known/agent-card.json."}, {"id":"markdown_negotiation","label":"serves Markdown to callers that ask for it","weight":3,"pass":true,"evidence":"GET / with Accept: text/markdown → 200 text/markdown with Vary: Accept."}, {"id":"mcp_server_card","label":"MCP server card published","weight":2,"pass":false,"disposition":"not_applicable","evidence":"No MCP server card found.","remediation":"Do not add one unless an MCP server exists."}, {"id":"api_catalog","label":"API catalog (RFC 9727)","weight":2,"pass":false,"disposition":"defer","evidence":"GET /.well-known/api-catalog → 404.","remediation":"Publish only after a stable OpenAPI description and catalog ownership exist."}, {"id":"agent_skills","label":"Agent Skills index","weight":2,"pass":false,"disposition":"not_applicable","evidence":"GET /.well-known/agent-skills/index.json → 404.","remediation":"Do not add one until the product exposes a real agent task."}, {"id":"web_bot_auth","label":"Web Bot Auth key directory","weight":2,"pass":false,"disposition":"defer","evidence":"GET /.well-known/http-message-signatures-directory → 404.","remediation":"Consider only with an owned signing-key storage and rotation process."} ], "implementation_snippets": { "machine_alternates": "\n", "json_ld_note": "The paid report supplies a paste-ready SoftwareApplication + Offer block after the owner confirms price, currency, billing period, availability and tax treatment.", "llms_full_note": "Generate from approved source content; do not blindly concatenate private, duplicate or outdated documentation." }, "limitations": [ "This is a fictional example, not a network audit of a live origin.", "A technical score measures discoverability and parseability, not model preference or commercial conversion.", "CDN-managed robots policy, authentication walls and dashboard-only settings require owner access and are reported separately.", "Expected-after score assumes the four changes are deployed correctly and re-audited under the same v2 check set." ], "provider": { "name": "Kamil Choiński", "trading_as": "KC-IT", "service": "https://kc-it.pl/services/agent-readability", "contact": "mailto:110kc3@gmail.com?subject=Request%20the%20%2449%20agent-readability%20report&body=Site%20URL%3A%0A" } }