# TheBotStack Complete Documentation Manifest > Comprehensive technical specification, API reference, and 24-point evaluation rubric for TheBotStack Agent Score & Diagnostic Suite. ## 1. Overview & Architecture TheBotStack is an open diagnostic benchmark measuring how effectively autonomous AI agents (Claude Code, Cursor, Copilot, Gemini CLI, Perplexity) can discover, ingest, understand, and interact with developer portals, APIs, and web services. Scores range from 0 to 100 with six letter grades: - A+ (95-100): Agent-Native Tier - A (90-94): Agent-Ready - B (80-89): Agent-Compatible - C (70-79): Optimization Required - D (60-69): Agent-Impaired - F (0-59): Agent-Inaccessible ## 2. The 24-Point Evaluation Rubric ### Pillar 1: Discoverability & AI Crawlers (20 Points) 1. `llms_txt_exists` (8 pts): Presence of /llms.txt with H1, blockquote, and curated links. 2. `llms_full_exists` (4 pts): Complete concatenated reference at /llms-full.txt. 3. `robots_ai_allowed` (5 pts): Explicit Allow directives for GPTBot, ClaudeBot, PerplexityBot, Google-Extended. 4. `sitemap_exists` (3 pts): Valid sitemap.xml reachable and linked in robots.txt. ### Pillar 2: Content Quality & Markdown (20 Points) 5. `markdown_negotiation` (8 pts): Intercepts Accept: text/markdown header or .md suffix to deliver clean markdown. 6. `clean_markdown` (5 pts): Strips navigation chrome, sidebars, cookie banners, and scripts. 7. `code_block_languages` (4 pts): All code fences include explicit language annotations (```typescript, ```python, ```bash). 8. `semantic_headings` (3 pts): Hierarchical H1 -> H2 -> H3 structure without skipped levels. ### Pillar 3: Context Window Budget (15 Points) 9. `token_budget` (8 pts): Page token payload remains under 15k tokens (full) or 30k tokens (partial). 10. `prompt_density` (4 pts): Technical information density exceeds 65% vs conversational filler. 11. `text_html_ratio` (3 pts): Brotli/gzip compressed payload without heavy inline base64/SVG assets. ### Pillar 4: Protocols & Agent Tooling (20 Points) 12. `mcp_support` (10 pts): Model Context Protocol (MCP) server endpoint or .well-known/mcp.json discovery. 13. `openapi_spec` (6 pts): Machine-readable openapi.json or swagger.yaml schema. 14. `structured_data` (4 pts): Schema.org JSON-LD structured metadata. ### Pillar 5: Agent Accessibility & Zero-Captcha (15 Points) 15. `ssr_static_delivery` (7 pts): Documentation immediately readable without client JavaScript hydration. 16. `zero_captcha_gating` (5 pts): No Cloudflare Turnstile, interstitial bot challenges, or 403 blocks for agent clients. 17. `clean_status_codes` (3 pts): Standard 200 OK, 304 Not Modified, and 404 responses without redirect loops. ### Pillar 6: Observability & Freshness (10 Points) 18. `freshness_headers` (5 pts): Last-Modified and strong ETag HTTP response headers. 19. `cache_control` (3 pts): Appropriate public Cache-Control headers for agent gateway caching. 20. `canonical_url` (2 pts): Explicit rel="canonical" tags to prevent duplicate embeddings. ## 3. Edge API Reference ### Live Scan Endpoint - `GET /api/scan?url=` - Query parameters: - `url` (string, required): Domain or full URL to inspect. - Response: Complete JSON audit with points per check, category breakdowns, and actionable remediation templates. ### Calculator Endpoint - `POST /api/calculate` - Request body: `{ "checks": { "llms_txt_exists": true, "markdown_negotiation": true, ... } }` - Response: Evaluated score, letter grade, and prioritized recommendations. ### Model Context Protocol (MCP) Server - `GET /api/mcp`: Returns MCP server discovery manifest. - `POST /api/mcp`: JSON-RPC 2.0 endpoint supporting `tools/list` and `tools/call`: - `calculate_agent_score` - `scan_agent_readiness` - `get_agent_leaderboard` ### Badge Shield Endpoint - `GET /api/badge?score=95&grade=A+&label=Agent%20Score` - Returns dynamic SVG badge for Markdown documentation and GitHub repositories.