Skip to content
Is Agentic

scholar-sidekick.com

Strong technical baseline

92/ 100

Technical readiness score

What should the prompt cover?

11 findings · 5 selected

Failures (1)

Warnings (10)

How the score adds up

45 checks

The agent partially completed the observed task

One run shows how an agent performed, but it does not determine the technical score.

Task

What does scholar-sidekick.com do and who is it for? Explain it back to me.

9 steps2 reasoning steps

home
docs
docs
/docs.md
/index.md
.well-known
docs
1 observed runView journey ↗

Critical access needs attention

These checks describe whether an ordinary agent can enter, read, and operate the public site.

  • Agents can reach the site

    Crawler access, bot defenses, and explicit agent policy.

    3 / 3 passed

  • Core content is available

    Useful content remains accessible without a fragile browser-only path.

    1 / 2 passed

  • Navigation fails safely

    Redirects and missing pages give agents a recoverable path.

    1 / 2 passed

  • Controls are understandable

    Forms and interactive controls expose usable names and structure.

    3 / 3 passed

Advertised capabilities need refinement

Optional surfaces appear only when the scan finds positive evidence that the site offers them.

Public website

Ready with gaps

80%

12 of 20 mature checks passed

API

Strong

95%

14 of 16 mature checks passed

Authentication

Strong

100%

3 of 3 mature checks passed

MCP

Strong

96%

5 of 6 mature checks passed

Fix these gaps first

Critical access gaps come first, followed by gaps in capabilities the site advertises.

  1. 01

    Agent-friendly 404s

    Return a real HTTP 404 (or 410) status for nonexistent paths - never a 200 with your app shell, which makes agents believe every path exists. For full credit, give the 404 response a short markdown body pointing agents at your sitemap, llms.txt, or docs index. Verify with `curl -s -o /dev/null -w "%{http_code}" https://yourdomain.com/some-path-that-does-not-exist` - it must print 404.

    Critical access
  2. 02

    Content without JavaScript

    Server-side render your homepage so AI crawlers see meaningful content without JavaScript. Ensure an H1 and 500+ chars of text in raw HTML.

    Critical access
  3. 03

    Markdown content negotiation (acceptmarkdown.com)

    On the responses that serve text/markdown via Accept negotiation, add Accept to the Vary header (Vary: Accept, Accept-Encoding). Without it, CDNs can serve the cached HTML variant to an agent asking for markdown (or vice versa), depending on which variant landed in cache first.

    Advertised capabilities
  4. 04

    MCP App view CSP

    Add a Content-Security-Policy (via HTTP header or <meta http-equiv>) that scopes 4 directive categories: connect-src includes your MCP server origin; frame-ancestors includes both https://chatgpt.com and https://claude.ai; form-action (or connect-src) scopes redirect targets; img-src / script-src / style-src list specific origins (not *). Permissive default-src * receives partial credit but loses points compared to a properly-scoped policy.

    Advertised capabilities
  5. 05

    Organization schema completeness

    Add Organization JSON-LD that includes both contactPoint (with email/phone and contactType) and address (PostalAddress). This lets AI verify your business legitimacy and answer contact queries.

    Advertised capabilities

Audit the checks behind the score

Applicable evidence is grouped by how it contributes to this preview model. Bonus checks appear only when they add points.

Essential11 of 15 passed · 68.9 / 80 points
  • Content without JavaScriptPartial (67%)

    6570 chars with H1 but flat heading structure

    Recommendation

    Server-side render your homepage so AI crawlers see meaningful content without JavaScript. Ensure an H1 and 500+ chars of text in raw HTML.

  • Not blocked by bot detectionPassed

    Site accessible to 6 AI agent user-agents

    Recommendation

    Allowlist known AI agent User-Agents (ChatGPT-User, ClaudeBot, Google-Extended, DeepSeekBot) in your WAF or bot-detection rules.

  • robots.txt agent-user policyPassed

    User-triggered agents explicitly allowed (chatgpt-user) + Content Signals ai-input=yes

    Recommendation

    Stop blocking user-triggered agents in robots.txt. Remove any 'Disallow: /' that applies to ChatGPT-User, Claude-User or Perplexity-User - including a blanket 'User-agent: * / Disallow: /', which covers them by default. These agents fetch a page only because a person just asked about you, so a block turns away your highest-intent traffic.

  • Redirect hygienePassed

    No meta-refresh stubs, JavaScript-redirect stubs, or cross-domain hops across 6 checked pages

    Recommendation

    Replace meta-refresh and JavaScript-only redirects with real HTTP 301/302 redirects. Non-JS agents never execute `location.href` or wait for a meta refresh - they see only the stub page. Verify with `curl -sI <url>` - you should see a Location header, not a 200 with a near-empty body.

  • Content behind authPassed

    All 5 sampled pages are publicly readable (5 with substantive content)

    Recommendation

    Serve your content pages without a login wall. Agents cannot complete auth flows while browsing - a 401/403 or a login-form page is invisible content. Keep public documentation public; if some content must stay gated, publish an ungated summary so agents can still represent it.

  • OpenAPI spec publishedPassed

    OpenAPI spec found at https://scholar-sidekick.com/openapi.json (version: 3.0.3)

    Recommendation

    Publish an OpenAPI (Swagger) specification at /openapi.json or /api/openapi.yaml. This is how agents understand your API surface automatically.

  • Markdown content negotiation (acceptmarkdown.com)Failed

    Two-representation negotiation works but Vary header missing Accept (got "rsc, next-router-state-tree, next-router-prefetch, next-router-segment-prefetch") - CDNs may cache wrong variant

    Recommendation

    On the responses that serve text/markdown via Accept negotiation, add Accept to the Vary header (Vary: Accept, Accept-Encoding). Without it, CDNs can serve the cached HTML variant to an agent asking for markdown (or vice versa), depending on which variant landed in cache first.

  • Agent crawler reachabilityPassed

    Reachable to all major AI crawlers - ChatGPT-User: reachable, ClaudeBot: reachable, Google-Extended: reachable, ora-agent: reachable, DeepSeekBot: reachable

    Recommendation

    Verify that major agent User-Agents can reach the homepage. If robots.txt, your WAF, or bot rules block them, remove or narrow the blocking rule. Add an allow rule only when your security setup denies them by default.

  • OAuth 2.0 supportPassed

    OAuth authorization server metadata at https://scholar-sidekick.com (issuer=https://scholar-sidekick.com)

    Recommendation

    Implement OAuth 2.0 for API authentication. Publish your authorization server metadata at /.well-known/oauth-authorization-server.

  • Scoped permissionsPassed

    Security schemes defined in OpenAPI spec

    Recommendation

    Support scoped API permissions (OAuth scopes or API key roles) so agents can request only the access they need.

  • JSON error responsesPassed

    API returns JSON error responses (404 at https://scholar-sidekick.com/api/v1/orank-probe-test)

    Recommendation

    Return structured JSON error responses with error codes, messages, and resolution hints. Agents can't parse HTML error pages.

  • MCP resources exposedPassed

    MCP server exposes 1 resource(s) via resources/list

    Recommendation

    If your MCP server advertises the resources capability in its initialize handshake, make sure resources/list returns at least one resource. If you don't intend to expose resources, omit the capability - the check returns na with no penalty for tool-only servers. Quality of the resources you do return is scored separately by mcp-resource-quality.

  • Agent-friendly 404sPartial (50%)

    Nonexistent paths return a real HTTP 404. For full credit, include a short markdown body (site map links, where to look next) so agents can recover.

    Recommendation

    Return a real HTTP 404 (or 410) status for nonexistent paths - never a 200 with your app shell, which makes agents believe every path exists. For full credit, give the 404 response a short markdown body pointing agents at your sitemap, llms.txt, or docs index. Verify with `curl -s -o /dev/null -w "%{http_code}" https://yourdomain.com/some-path-that-does-not-exist` - it must print 404.

  • MCP App view reachablePassed

    Inline ui:// view delivered with valid HTML and no auth wall

    Recommendation

    Make sure your MCP App view is reachable and public. For inline ui:// resources: return HTML with <!DOCTYPE html> and no login form. For external HTTP origins (referenced via <base href> or <meta refresh>): return 200 OK + text/html without requiring auth (no 401/403, no password input in the body).

  • MCP App view CSPPartial (75%)

    CSP covers 3/4 categories: -connect-src covers MCP origin; +frame-ancestors covers ChatGPT and Claude.ai; +form-action / connect-src covers redirects; +asset directives are scoped

    Recommendation

    Add a Content-Security-Policy (via HTTP header or <meta http-equiv>) that scopes 4 directive categories: connect-src includes your MCP server origin; frame-ancestors includes both https://chatgpt.com and https://claude.ai; form-action (or connect-src) scopes redirect targets; img-src / script-src / style-src list specific origins (not *). Permissive default-src * receives partial credit but loses points compared to a properly-scoped policy.

Recommended23 of 30 passed · 18 / 20 points
  • Developer resource discoverabilityPartial (67%)

    Agent found developer resources by name including developer portal (1 relevant pages)

    Recommendation

    Make your developer resources (API docs, OpenAPI spec, auth docs, webhooks, MCP server) discoverable by name. Publish them at predictable URLs, list them in llms.txt, and include your product name in page titles and headings so search engines surface them for name-based queries.

  • Brand name discoverabilityPassed

    scholar-sidekick.com appears at position #2 in a clean brand-name search for "Scholar Sidekick" (1 total match)

    Recommendation

    Make sure a clean search for your brand name returns your own domain in the top results. If it does not, your brand may be too generic, conflict with a more established term, or not yet indexed. Strengthen brand-name search by claiming consistent NAP across listings, earning press mentions that link to the canonical domain, and avoiding redirect chains that mask the apex domain in search results.

  • robots.txt AI crawler policyPartial (50%)

    AI crawlers explicitly allowed (gptbot, oai-searchbot, claudebot, perplexitybot, google-extended, applebot-extended) - consider blocking training-only crawlers (CCBot, ByteSpider) to earn full credit + Content Signals (ai-train=yes, search=yes, ai-input=yes)

    Recommendation

    Add explicit AI crawler directives in robots.txt. Allow the crawlers that feed answer engines ('User-agent: GPTBot' / 'Allow: /', same for ClaudeBot, PerplexityBot, OAI-SearchBot), and restrict training-only crawlers (CCBot, ByteSpider) with 'Disallow: /'. Content Signals ('Content-Signal: search=yes, ai-train=no') earns the same credit.

  • Sitemap existsPassed

    Valid sitemap found at https://scholar-sidekick.com/sitemap.xml with 81 entries

    Recommendation

    Add a valid XML sitemap at /sitemap.xml listing all indexable URLs. Include lastmod dates and keep it under 50MB.

  • Content efficiencyPassed

    Content efficiency: 5.31% (7716 text chars / 142KB HTML)

    Recommendation

    Reduce markup overhead so readable text is at least 5% of your HTML. Strip unused inline scripts/styles, server-render content instead of shipping large JSON hydration blobs, and keep wrapper nesting shallow.

  • JSON-LD structured dataPassed

    Rich JSON-LD identity: Organization with name, description, url, and sameAs/logo/address (7 block(s))

    Recommendation

    Add JSON-LD structured data to your homepage using the identity type that matches your site - SoftwareApplication for products, Organization or LocalBusiness for companies, Person for personal sites, Article for blogs - with name, description, url, and type-appropriate fields (offers, sameAs, author) so AI can parse your identity programmatically.

  • Public API/docs linked from homepagePassed

    API/docs link found on homepage and resolves: /docs

    Recommendation

    Publish API documentation at a discoverable URL (/docs, /api, /developers). Include authentication, endpoints, and example requests.

  • Agent instruction / when-to-usePartial (67%)

    Agent instruction file at /.well-known/agent-skills/ but no explicit when-to-use guidance

    Recommendation

    Tell agents when to reach for you: add a 'when to use this' section to your llms.txt (or a dedicated agent-instructions file) that names your best-fit use cases and how an agent should call you. Be specific about the jobs you are right for - generic marketing copy does not read as guidance.

  • Metadata completenessPassed

    All metadata signals present: canonical URL, lang="en", og:image, og:type

    Recommendation

    Add all four signals to your homepage: <link rel="canonical">, <html lang="...">, <meta property="og:image">, and <meta property="og:type">. Agents use these for entity resolution and attribution.

  • Organization schema completenessPartial (50%)

    Organization schema found but missing: address

    Recommendation

    Add Organization JSON-LD that includes both contactPoint (with email/phone and contactType) and address (PostalAddress). This lets AI verify your business legitimacy and answer contact queries.

  • Trust anchor pagesPartial (50%)

    Only Privacy page verified - missing: About, Contact

    Recommendation

    Publish real /about, /contact, and /privacy pages with at least 500 characters of content each. These are the pages AI agents check to verify your business is legitimate before recommending you.

  • Page token budgetPassed

    All 10 measured pages fit an agent context budget (largest ~4K tokens)

    Recommendation

    Keep each page's extracted text under ~100K characters (~25K tokens) so it fits an agent's context window without truncation. Split oversized reference pages into focused per-topic documents and link them from an index. Check a page with `curl -s <url> | wc -c` and remember agents read the extracted text, not the raw HTML.

  • Code fence validityPassed

    Code fences balanced across 1 markdown document

    Recommendation

    Close every fenced code block (``` or ~~~) in your served markdown. CommonMark treats everything after an unclosed fence as code, so an agent parsing the document silently loses the rest of it. Count fence lines per file - the total must be even.

  • Developer portalPassed

    Developer portal found at /developers

    Recommendation

    Create a developer portal at /developers with API keys, documentation, quickstart guides, and a sandbox environment.

  • Public API with reachable endpointsPassed

    Documented REST API detected; endpoints require authentication (API key / OAuth), which is expected for agent access. Best-of-protocols score: 7/7.

    Recommendation

    Expose a public REST or GraphQL API. AI agents need programmatic access - not just a web UI - to integrate with your product.

  • Agent onboarding frictionPassed

    Low friction onboarding: free tier available, sandbox/test environment, zero-auth access

    Recommendation

    Offer a free tier or trial, self-serve API key generation, and a sandbox environment. Agents can't fill out 'contact sales' forms.

  • MCP server / manifestPassed

    MCP server connected via Streamable HTTP - scholar-sidekick-app v2.0.1 (protocol 2025-11-25)

    Recommendation

    Build an MCP (Model Context Protocol) server exposing your API as tools. Use Streamable HTTP transport for full score. This lets Claude, ChatGPT, and other AI agents call your product natively.

  • Rate limit response headersPartial (50%)

    REST rate-limit headers documented in OpenAPI spec, but not observed on a live response (API requires authentication).

    Recommendation

    Return standard rate-limit headers on your API responses (the RFC RateLimit headers, plus Retry-After on a 429) so agents can self-throttle in real time, and document the conventions alongside your API.

  • Idempotency-Key supportPassed

    REST Idempotency-Key header found on POST /api/format in OpenAPI spec

    Recommendation

    Support an idempotency key on your write operations and declare it where agents can read it: an Idempotency-Key header parameter on your POST/PUT/PATCH operations in your OpenAPI spec for REST, or a client-supplied id argument on your GraphQL mutations. Agents retry on network failures, and without this a retry can double-charge or duplicate a record.

  • REST typed error modelPassed

    REST typed error model documented at https://scholar-sidekick.com/openapi/openapi.yml (REST API is auth-gated; credited via documentation).

    Recommendation

    Document your error responses in your OpenAPI spec: give 4xx and 5xx responses a typed error schema (or use RFC 9457 application/problem+json). A consistent error object with a machine-readable code and a human-readable message lets agents handle failures without guessing.

  • REST versioning / deprecation policyPassed

    REST versioning / deprecation policy documented at https://scholar-sidekick.com/openapi/openapi.yml (REST API is auth-gated; credited via documentation).

    Recommendation

    Declare a versioning policy agents can rely on: version your API (in the URL path or a version header) and publish how you signal deprecation (a Sunset/Deprecation header or a documented timeline). Agents avoid integrating against a surface that can change without warning.

  • REST pagination patternPassed

    REST pagination pattern documented at https://scholar-sidekick.com/openapi/openapi.yml (REST API is auth-gated; credited via documentation).

    Recommendation

    Use a consistent, documented pagination shape on your list endpoints (cursor-based preferred) and define the pagination fields in your OpenAPI response schemas, so agents can page through results without guessing the shape.

  • REST async-job patternPassed

    REST async-job pattern documented at https://scholar-sidekick.com/openapi/openapi.yml (REST API is auth-gated; credited via documentation).

    Recommendation

    For long-running operations, return 202 Accepted and point agents at where to poll for the result (a status/location reference plus a job identifier in the body), documented in your OpenAPI spec, so work that does not finish in one request is still followable.

  • CLI tool availablePassed

    CLI package found on npm: scholar-sidekick-cli

    Recommendation

    Publish an official CLI tool on npm, PyPI, or Homebrew. A CLI lets agents and developers script interactions with your product without building API integrations from scratch.

  • Multi-language SDK packagesPartial (67%)

    SDK packages found in npm, pypi

    Recommendation

    Publish official SDK packages across multiple language ecosystems (npm, PyPI, Go modules, RubyGems). Auto-generate them from your OpenAPI spec using tools like openapi-generator. For each package set the project URL or homepage to your product domain (package.json `repository`/`homepage`, PyPI `Home-Page` or `project_urls`, RubyGems `homepage_uri`) - this is how agents verify the package is your official SDK.

  • REST response schema coveragePassed

    100% of operations define typed response schemas, 83% use application/json

    Recommendation

    Define typed JSON response schemas for every endpoint in your OpenAPI spec. Agents rely on these to know what fields they will get back; missing or partial schemas force trial-and-error.

  • MCP Apps supportPassed

    MCP Apps: 1 ui:// resources, 4 UI-enabled tools (audit_citations, verify_citation, format_citation), correct MIME type

    Recommendation

    Add MCP Apps support to your MCP server using @modelcontextprotocol/ext-apps. Expose ui:// resources and add _meta.ui.resourceUri to tools so agents can render interactive UIs directly in conversation.

  • API schema complexity analysisPassed

    REST: agent-friendly schema (12 operations, operationIds present, well-documented)

    Recommendation

    Make your API spec self-describing: a unique operationId and a description on every operation, typed parameters, and response schemas. For GraphQL, a fully typed schema with a documented cost or rate limit reads best.

  • Function calling compatibilityPassed

    Compatible: 12/12 ops with IDs, 12/12 with typed schemas

    Recommendation

    Ensure API endpoints have unique operation IDs, typed schemas, and descriptions compatible with LLM function-calling formats.

  • MCP resource qualityPassed

    1/1 resources read with valid mimeType and non-empty content

    Recommendation

    Ensure every resource returned by resources/list reads cleanly via resources/read: declare a valid mimeType, return non-empty content, and make sure any URIs in the content resolve. Broken or empty resources break agent UX silently.

Bonus signals52 positive · +5 points
  • ARD / ai-catalogPassed

    ARD catalog valid (spec 1.0) - 11/11 entries

    Recommendation

    Add a trustManifest (identity, attestations, or signature) to entries for progressive trust

  • ARD entry validityPassed

    All 11 entries valid with domain-anchored urn:air identifiers

    Recommendation

    Make every ai-catalog.json entry fully valid: a domain-anchored urn:air identifier, a displayName, a media type, and exactly one of url or data.

  • Listed in MCP registriesPassed

    Verified in 2 registries: Smithery (scholar-sidekick/remote) [entry-to-product], npm (scholar-sidekick-mcp) [entry-to-product] - 3229 agent uses

    Recommendation

    Register your MCP server on Smithery (smithery.ai) or mcp.so so agent platforms can discover your tools. Link the registry entry from your homepage or docs for bi-directional verification.

  • NPM/PyPI SDK packagePassed

    NPM package found: scholar-sidekick-mcp - "MCP server that catches AI-fabricated citations: verifies a claimed title against the real record at its DOI or PMID (the Topaz et al. Lancet 2026 pattern), audits whole bibliographies, and checks retraction and open-access status — plus citation formatti"

    Recommendation

    Publish a JavaScript/TypeScript SDK package on npm so developers can integrate your API programmatically. In package.json set `repository` to your source repo and `homepage` to your product domain - these links are how agents confirm the package is your official SDK rather than a third-party tool with a similar name.

  • Listed on skills.shPassed

    3 official skills published on skills.sh - 52 total installs (skills.sh/mlava)

    Recommendation

    Publish agent skills on skills.sh so AI agents can discover your product's capabilities. Create a SKILL.md in your GitHub repo and register it with 'npx skills add'. See skills.sh/docs.

  • Registry brandingPassed

    MCP manifest has full branding (name, icon, description) at /.well-known/mcp/server-card.json

    Recommendation

    Give your MCP server-card (at /.well-known/mcp/server-card.json) a display name, an icon or logo, and a description - all three together are what reads as a complete, branded listing agents can present.

  • ChatGPT app listedPassed

    ChatGPT plugin manifest found: "Scholar Sidekick"

    Recommendation

    Submit your app to the ChatGPT apps / connectors directory (the apps-in-ChatGPT surface) so ChatGPT users can discover and use your product.

  • Agent discovery filePassed

    Agent Skills index (agentskills.io) found at /.well-known/agent-skills/index.json with 7 skill(s)

    Recommendation

    Publish an Agent Skills index at /.well-known/agent-skills/index.json that lists your capabilities, with each skill carrying a name and a description so agents can find and parse what you offer.

  • Agent Skills index conformance (v0.2.0)Passed

    Index v0.2.0 conformant; verified SHA-256 of "resolve-identifier" (6 other skills present)

    Recommendation

    Upgrade /.well-known/agent-skills/index.json to the v0.2.0 schema: add "$schema": "https://schemas.agentskills.io/discovery/0.2.0/schema.json", and give every entry a type (skill-md or archive), url, and digest. Use "digest": "sha256:<64 lowercase hex chars>" (e.g. "digest": "sha256:a3f1...") - a bare "sha256": "<hex>" field is also accepted. Compute the value from the artifact's raw bytes.

  • A2A / agent-cardPassed

    A2A Agent Card found: "Scholar Sidekick"

    Recommendation

    Publish an Agent-to-Agent (A2A) agent card at /.well-known/agent-card.json describing your agent's capabilities, skills, and contact endpoint.

  • MCP well-known discoveryPassed

    MCP server discoverable at standard path https://scholar-sidekick.com/.well-known/mcp.json

    Recommendation

    Serve your MCP server at /.well-known/mcp, publish a server-card.json at /.well-known/mcp/server-card.json, or reference it in llms.txt so agents can discover it automatically without manual URL input.

  • HTTP Link headers (RFC 8288)Passed

    RFC 8288 Link header advertises: sitemap, describedby, service-desc, service-doc, api-catalog, alternate(markdown)

    Recommendation

    Add HTTP Link: response headers (RFC 8288) advertising your sitemap, markdown alternates, API service descriptions, and API catalog. Example: Link: </sitemap.xml>; rel="sitemap", </index.md>; rel="alternate"; type="text/markdown".

  • Markdown URL fallbackPassed

    Full markdown fallback support. Homepage (https://scholar-sidekick.com/index.md) and all 3 sampled content pages return markdown: https://scholar-sidekick.com/citation-api.md, https://scholar-sidekick.com/developers.md, https://scholar-sidekick.com/docs.md

    Recommendation

    Let agents fetch markdown by appending .md to page URLs. Required for any credit: serve a markdown homepage at /index.md. For full credit (2/2): also serve a .md twin for each content page (e.g. /docs/auth -> /docs/auth.md). Content-Type should be text/markdown and the body should start with a top-level heading (not HTML).

  • Modular llms.txt per product areaPassed

    Modular llms.txt files found for sections: docs, tools

    Recommendation

    Add per-section llms.txt files (e.g. /docs/llms.txt, /api/llms.txt, /developers/llms.txt) so agents can fetch scoped context for specific product areas instead of the whole manual.

  • Sitemap freshness (lastmod)Passed

    100% of 81 sampled sitemap entries carry lastmod; newest is 2 day(s) old

    Recommendation

    Add <lastmod> dates (W3C datetime, e.g. 2026-08-01) to your sitemap entries and update them when content actually changes. Aim for lastmod on at least half your entries with the newest within the last year. Verify with `curl https://yourdomain.com/sitemap.xml | grep lastmod`.

  • llms.txt existsPassed

    Found the llms.txt at https://scholar-sidekick.com/llms.txt.

    Recommendation

    Create an llms.txt file at your domain root (/llms.txt) - the AI equivalent of robots.txt. Write at least 100 characters of real content: what your product is, what it does, and links to your key docs. Then verify it with `curl https://yourdomain.com/llms.txt` - you should see your text, not HTML. If your app returns its homepage for every URL (common with single-page apps), add a static file route so the raw text is served. A placeholder with just a heading earns no credit.

  • llms.txt formattingPassed

    The llms.txt is well-formatted: 181 lines with markdown links, 27,363 characters in total.

    Recommendation

    Format your llms.txt as a navigation index: start with a markdown heading, include markdown links to deeper resources, and keep it under 30,000 characters. If you have more to say, move long-form content into /llms-full.txt or per-section files (e.g. /docs/llms.txt, /api/llms.txt) and link to them from the main index.

  • Skills.sh skill qualityPartial (50%)

    Skills.sh presence exists but limited - 3 skills (goal: 5+), 52 installs (goal: 200+)

    Recommendation

    Expand your skills.sh presence with multiple skill repos covering different use cases. Add descriptive skill names, clear SKILL.md files, and organize by capability area.

  • JSON-LD entity linking (sameAs)Passed

    Strong entity linking via sameAs: wikidata.org, github.com

    Recommendation

    Add sameAs links in your JSON-LD structured data pointing to your Wikipedia page, Wikidata entry, GitHub org, and social profiles. This helps AI disambiguate your brand from similarly named entities.

  • Speakable content markupPassed

    Speakable property found in JSON-LD - agents know which content to present conversationally

    Recommendation

    Add schema.org speakable markup to your homepage indicating which sections are suitable for AI assistant text-to-speech readout. Use a Speakable property with CSS selectors targeting your key value proposition.

  • Schema type breadthPassed

    Rich schema vocabulary: BreadcrumbList, Service, FAQPage

    Recommendation

    Expand your JSON-LD beyond Organization/WebSite. Add FAQPage for common questions, Service or Product for offerings, AggregateRating or Review for social proof, and BreadcrumbList for navigation context.

  • llms.txt links resolvePassed

    All 5 probed llms.txt links resolve to real content

    Recommendation

    Make every link your llms.txt declares resolve to real content. Verify each one with `curl -L <url>` - you should see the linked document, not your homepage. If your app returns the homepage shell for unknown paths (common with single-page apps), a 200 status is not proof: check the body. Fix or remove any dead link; agents that follow the index treat a broken link as a dead end.

  • Markdown alternate linkPassed

    Markdown alternate advertised and verified: https://scholar-sidekick.com/index.md serves markdown

    Recommendation

    Advertise a markdown twin of each page with <link rel="alternate" type="text/markdown" href="..."> in the HTML head (or an equivalent Link response header), and make sure the advertised URL actually serves markdown - an advertisement pointing at HTML is worse than none. Verify the target with `curl -s <href>` and check the body starts with a heading, not <!doctype html>.

  • Markdown frontmatter metadataPassed

    Frontmatter with title + description, last-updated, and canonical on /mcp.md

    Recommendation

    Open your served markdown docs with a --- frontmatter block carrying title plus at least one of description, canonical, or last-updated. Agents read frontmatter as document metadata without scraping. A Link: rel="canonical" response header also satisfies the canonical slot.

  • API catalog (RFC 9727)Passed

    RFC 9727 api-catalog with 2 API link(s) and rfc9727 profile

    Recommendation

    Publish an API catalog at /.well-known/api-catalog per RFC 9727. Serve it with Content-Type: application/linkset+json;profile="https://www.rfc-editor.org/info/rfc9727" and include a 'linkset' array with item entries pointing to your OpenAPI specs and service descriptions.

  • Markdown agent docsPassed

    Path-suffix markdown docs served with text/markdown content-type: /mcp.md, /developers.md, /auth.md, /index.md

    Recommendation

    Pick one: (a) return Content-Type: text/markdown on GET <homepage> when the request sends Accept: text/markdown, or (b) publish a static /llms.md, /auth.md, or /agents.md file at your root with real markdown content. Option (b) is usually a single static file. This is the cold-discovery path for agents that land at your homepage from web search without reading llms.txt first.

  • MCP tool descriptionsPassed

    All 4 tools on product MCP have detailed descriptions (>= 20 chars)

    Recommendation

    Add detailed descriptions (>= 20 chars) to every MCP tool. Agents use these to decide which tool to call - vague descriptions lead to wrong tool selection.

  • MCP parameter schemasPassed

    4/4 tools on product MCP have parameter schemas, 4 with required fields

    Recommendation

    Define inputSchema with typed properties and required arrays for each tool. Agents need schema info to construct valid tool calls without guessing.

  • MCP server identityPassed

    product MCP identifies as "scholar-sidekick-app" v2.0.1 with instructions

    Recommendation

    Set server name, version, and instructions in your MCP server's initialize response. Instructions help agents understand your server's purpose and constraints.

  • MCP tool listingPartial (67%)

    docs MCP exposes 7 tools - large docs toolsets are hard for agents to choose between; consider consolidating

    Recommendation

    Expose 3+ tools via your MCP server's tools/list endpoint. Cover your core API surface - agents need tools for read, write, and search operations.

  • MCP tool namingPartial (75%)

    docs MCP tool names are consistent and descriptive, but none reference content resources (doc/article/page) - agents discovering this server may miss its purpose

    Recommendation

    Use consistent naming conventions (snake_case or camelCase) for all MCP tools. Names should be descriptive (>= 4 chars) and not generic (avoid 'run', 'get', 'do').

  • MCP auth mechanismPassed

    docs MCP is public - correct posture for documentation surface

    Recommendation

    Protect your MCP server with OAuth 2.0 authentication. Publish authorization server metadata at /.well-known/oauth-authorization-server for automatic agent auth flows.

  • OAuth Protected Resource metadata (RFC 9728)Passed

    RFC 9728 metadata: resource=https://scholar-sidekick.com/api, authorization_servers (1), bearer_methods_supported

    Recommendation

    Publish RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource. Include the resource field plus enough supporting metadata - your authorization servers, supported scopes, accepted bearer methods - that an agent can work out how to authenticate without first triggering a 401.

  • auth.md existsPassed

    auth.md at https://scholar-sidekick.com/auth.md served as text/markdown; charset=utf-8 (5000 chars)

    Recommendation

    Publish /auth.md as a markdown prose walkthrough of how agents should obtain credentials. Serve it with Content-Type: text/markdown, lead with a top-level heading, and write at least ~200 chars of real content (not just a placeholder). See the WorkOS auth.md draft at https://workos.com/auth-md.

  • auth.md structurePassed

    WorkOS auth.md structure at https://scholar-sidekick.com/auth.md - 6/7 walkthrough sections (found Discover, Pick a method, Register, Claim, Use credential, and Revocation); anchors: oauth-protected-resource, oauth-authorization-server, and agent_auth; documents partial spec support (does not implement: OAuth client registration)

    Recommendation

    Structure /auth.md as the WorkOS spec prescribes: sections for Discover, Pick a method, Register, Claim, Use the credential, Errors, and Revocation, with spec anchor keywords (agent_auth, register_uri, identity_assertion, id-jag, WWW-Authenticate). Reference https://workos.com/auth-md.

  • auth.md walkthrough simulationPassed

    Static fallback (deep check disabled): PRM + AS metadata both reachable with agent_auth.register_uri (https://scholar-sidekick.com/account); walkthrough discoverable end-to-end

    Recommendation

    Make your published auth-discovery chain traversable end to end: an agent starting at /auth.md (or your protected-resource metadata) should be able to follow the links to your authorization-server metadata and registration endpoint without hitting a dead link. Test the whole path, not just each file in isolation.

  • Agent auth discovery metadataPassed

    PRM + AS metadata cross-linked; agent_auth has register_uri (https://scholar-sidekick.com/account), identity_types_supported [anonymous] with per-type *_supported blocks, and skill -> https://scholar-sidekick.com/auth.md (also advertised: claim_uri, revocation_uri; events_supported absent)

    Recommendation

    Publish RFC 9728 protected-resource metadata at /.well-known/oauth-protected-resource on your resource server (the host that actually serves the API, e.g. api.<apex>) with `resource` and `authorization_servers`. Publish RFC 8414 authorization-server metadata at /.well-known/oauth-authorization-server on the AS origin, and include the WorkOS auth.md `agent_auth` block with `register_uri`, `identity_types_supported` drawn from the spec enum (`anonymous`, `identity_assertion` - variants like `verified_email` or `urn:ietf:params:oauth:token-type:id-jag` belong inside `identity_assertion.assertion_types_supported`, not at the top level), and a sibling per-type block for each advertised type (`anonymous.credential_types_supported`; `identity_assertion.assertion_types_supported` + `credential_types_supported`) so agents can look up the request shape. Cross-link by listing the AS origin in PRM `authorization_servers`, and point `agent_auth.skill` back at your published /auth.md. Spec: https://workos.com/auth-md.

  • Agent auth WWW-Authenticate hintPassed

    401 at /api with spec-shaped WWW-Authenticate hint: Bearer realm="Scholar Sidekick", resource_metadata="https://scholar-sidekick.com/.well-known/oauth-protected-resource",

    Recommendation

    Return a 401 carrying a spec-shaped `WWW-Authenticate: Bearer resource_metadata="<your protected-resource metadata URL>"` header on your API's primary entry points, so an agent learns your auth requirements from one request instead of hunting for the well-known document. Point the metadata URL at /.well-known/oauth-protected-resource on the host that serves the API. Spec: https://workos.com/auth-md.

  • agent_auth endpoints reachablePassed

    agent_auth endpoints reachable (source: AS metadata agent_auth block) - register_uri: HTTP 200, claim_uri: HTTP 200, revocation_uri: HTTP 200

    Recommendation

    Make sure the URIs you advertise (in the AS metadata agent_auth block OR in your /auth.md prose) for register_uri, claim_uri, and revocation_uri actually resolve. An OPTIONS preflight should return any HTTP status (2xx/3xx/4xx that isn't 404). DNS-level failure or a 404 means the discovery block / prose is stale - either remove the URI or stand up the endpoint.

  • MCP error handlingPassed

    product MCP returns structured JSON-RPC errors with code and message

    Recommendation

    Return structured JSON-RPC errors (with code and message) when agents call invalid tools or pass bad arguments. Don't crash or return empty responses.

  • MCP modern transportPassed

    product MCP uses modern Streamable HTTP transport

    Recommendation

    Upgrade your MCP server from legacy SSE to Streamable HTTP transport. Streamable HTTP is the current standard and supports bidirectional communication.

  • WebMCP supportPassed

    Imperative WebMCP API detected (document.modelContext in inline script).

    Recommendation

    Expose in-page tools via WebMCP, the W3C draft standard for browser-resident AI agents. Add toolname and tooldescription attributes to your action forms - they survive into server-rendered HTML, so scanners and agents can see them - and register richer tools from client-side JS with document.modelContext.registerTool() (navigator.modelContext is the deprecated pre-Chrome-150 alias). Chrome ships WebMCP in 157 after the 149-156 origin trial.

  • MCP tool annotationsPassed

    product MCP: 4/4 tools have behavioral annotations (readOnlyHint/destructiveHint)

    Recommendation

    Add behavioral annotations (readOnlyHint, destructiveHint) to your MCP tools. Agents use these to avoid destructive actions without user confirmation.

  • MCP server-card.jsonPartial (75%)

    MCP server card found at https://scholar-sidekick.com/.well-known/mcp/server-card.json (7 tools advertised) (drift: card advertises 7 tools, live server has 4)

    Recommendation

    Publish a server card at /.well-known/mcp/server-card.json describing your MCP server. Required fields: name, description, version, serverUrl, tools[]. This lets agents preview your server before opening a transport connection.

  • Product + docs MCP coveragePassed

    You run both: a product MCP server (https://scholar-sidekick.com/api/apps/mcp) for actions and a docs MCP server (https://scholar-sidekick.com/api/mcp) for documentation.

    Recommendation

    Beyond your product MCP server, expose a documentation MCP surface so agents can pull your docs and reference material over the same protocol they use to act. Covering both the 'do' and the 'learn' surfaces over MCP earns this.

  • REST batch / bulk endpointPassed

    REST batch / bulk endpoint documented at https://scholar-sidekick.com/openapi/openapi.yml (REST API is auth-gated; credited via documentation).

    Recommendation

    Offer a batch endpoint that accepts an array of operations in one request, documented in your spec, so an agent acting on many items can do it in bulk instead of looping one call at a time.

  • Accessible document structurePassed

    Server HTML is a well-structured document (main=true, landmarks=4/4, h1=1, maxHeadingSkip=1).

  • Native interactive controlsPassed

    122 native controls, 0 non-native div-soup affordances (100% native).

  • Accessible names on controlsPassed

    122/122 interactive elements have a computable accessible name (100%).

  • Accessibility-tree injection safety (bonus)Passed

    No hidden instruction text detected in accessibility-tree attributes or off-screen content.

  • A2UI / generative UI supportPassed

    MCP Apps: 1 interactive ui:// resource(s) for in-conversation UI rendering

    Recommendation

    Support Agent-to-UI rendering via MCP Apps (ui:// resources), OpenAI Apps SDK, or generative UI patterns that let agents render interactive UIs in conversation.

  • MCP Apps UI qualityPassed

    MCP Apps resource quality: correct MIME type, valid HTML5, dark mode support

    Recommendation

    Ensure your MCP Apps resources use MIME type text/html;profile=mcp-app, include <!DOCTYPE html>, and add <meta name="color-scheme" content="light dark"> for dark mode. Never hardcode secrets in resource HTML.

Inspect the underlying audit

The complete Ora audit uses evidence from the scan on . After applying changes, run another scan from the homepage to refresh these recommendations.

Source: Ora API

Snapshot 2026-08-20T20-09-25-293Z