AI-SEO / AEO / GEO audit MCP for any public URL. Scores schema.org coverage, robots.txt and llms.txt health, canonical and OpenGraph setup, and AI-citation likelihood.
Scored across 20 tools
The four score_* tools (ai_overview_eligibility, citation_worthiness, test_citation, agentic_browsing) and the audit/check overlaps (audit_page vs check_technical vs audit_canonical, audit_site vs audit_sitemap vs check_sitemap) create real boundary risk. However, each description explicitly names the sibling tool it should not be confused with and explains when to prefer which, which rescues most ambiguity.
Strong, readable verb/noun prefixes (audit_, check_, score_, rewrite_) dominate. A few tools break the pattern with noun-first ordering (llms_txt_generate, llms_txt_validate, pricing_generate, report_save), so it's not fully uniform but still predictable.
20 tools is on the heavy side, and several are explicitly redundant composition targets (audit_canonical, check_technical, check_robots, check_sitemap are all absorbed into audit_page/audit_site). The breadth of the domain partially justifies the count, but the set could be tighter.
The surface covers auditing, technical checks, scoring across multiple engines, content rewriting (AEO/GEO), file generation (llms.txt, pricing.md), entity extraction, comparison, and reporting. No obvious lifecycle gap for an SEO/AEO audit toolset.
Audit a page's canonical link integrity: presence, self-reference, cross-domain mismatches, trailing-slash hygiene, and og:url consistency.
Read-only. One HTTP GET to fetch the HEAD section.
Deterministic, rule-based; no LLM.
When to use: a focused canonical-only audit (e.g. debugging a duplicate-content issue). For a full HEAD audit including OpenGraph, hreflang, noindex, title, use check_technical. For everything-on-a-page, use audit_page.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public URL whose canonical link tag and og:url consistency you want to audit. Must be a fully-qualified http(s) URL. The tool fetches the URL (following redirects) and inspects only the <head> section; the body is not parsed. | |
| respect_robots | No | If true (default), respect robots.txt before fetching. Set false only for auditing your own site where you've intentionally blocked crawlers. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| og_url | Yes | |
| findings | Yes | |
| canonical | Yes | |
| fetched_at | Yes | |
| cross_domain | Yes | Whether the canonical points to a different domain. |
| self_referencing | Yes | Whether the canonical points to the audited URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds behavioral context beyond annotations: read-only, one HTTP GET, only HEAD section, deterministic and rule-based. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with purpose. Three short paragraphs, no fluff. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description need not explain return values. It covers scope, behavior, and usage conditions sufficiently. Complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds extra context for the url parameter (must be fully-qualified, follows redirects, only inspects <head>), which adds value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool audits canonical link integrity including presence, self-reference, cross-domain mismatches, trailing-slash hygiene, and og:url consistency. It distinguishes itself from sibling tools like audit_page and check_technical.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (focused canonical-only audit) and when not to (use check_technical for full HEAD audit, audit_page for everything-on-a-page). Provides concrete alternative tool names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full AI-SEO audit of a single URL: returns categorized findings (info/warning/error) with severity, fix instructions, and a 0-100 composite score plus per-dimension subscores.
Read-only. Fetches the URL once and runs every sub-audit (schema, robots, technical, sitemap, AI-Overview eligibility) against the response. No writes, no third-party APIs, no auth required, no rate limits beyond polite per-host throttling.
Deterministic, rule-based scoring; no LLM calls. Same URL + same input flags returns the same score.
Supports render: "static" | "headless". Default static (fast, raw HTML only). Use headless for React/Vue/Angular SPAs — adds 3-10s and requires the optional playwright-core peer dep plus a one-time npx playwright install chromium.
When to use: the default entry point for audit any page. Use this instead of calling check_technical / audit_schema / check_robots / check_sitemap / score_ai_overview_eligibility individually unless you specifically need only one dimension - this tool composes all of them.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public URL to audit. Must be a fully-qualified http(s) URL that returns HTTP 200 (redirects are followed). The tool fetches this URL once and runs every sub-audit (schema, robots, technical, sitemap, AI-Overview eligibility) against the response. | |
| render | No | Rendering mode. `static` (default) fetches raw HTML via HTTP — fast (<1s) but misses JS-rendered content typical of SPAs (React/Vue/Angular landing pages). `headless` spins up Playwright Chromium, waits for networkidle, and audits the rendered DOM — adds 3-10s per audit and requires `playwright-core` installed plus a one-time `npx playwright install chromium`. Use `headless` when the static audit shows `content_quality: "spa_empty"` or you know the target is JS-rendered. | static |
| respect_robots | No | If true (default), the tool checks robots.txt before fetching and skips disallowed paths, returning a robots_blocked finding instead. Set to false ONLY for auditing your own site where you've intentionally blocked crawlers and need the audit to bypass that block. | |
| generate_report | No | If true, return a standalone HTML scorecard in the `report_html` field. The HTML is self-contained (no external dependencies) and can be saved as a .html file or pasted to Gist/CodePen. Default false to keep audits cheap. | |
| include_raw_html | No | If true, return the full raw HTML in the response under `raw_html`. Default false. Set true only when you need to inspect markup that wasn't captured by the structured findings; the payload can be large. |
| Name | Required | Description |
|---|---|---|
| url | Yes | The URL that was audited. |
| grade | Yes | Letter grade derived from the numeric score. |
| score | Yes | Composite 0-100 AI-citation score. |
| findings | Yes | All findings emitted by the sub-audits, deduplicated. |
| raw_html | No | Full raw HTML response. Present only when include_raw_html=true. |
| fetched_at | Yes | UTC ISO-8601 timestamp of the fetch. |
| score_caps | Yes | Hard blockers that capped the composite score (e.g. noindex, AI bots blocked). Empty when none fired. |
| report_html | No | Self-contained HTML scorecard. Present only when generate_report=true. |
| content_quality | Yes | Classification of the fetched HTML's readiness. spa_empty means audit results are degraded. |
| citation_verdict | Yes | Prepended block summarizing whether AI assistants will cite this page and why. |
| dimension_scores | Yes | Per-dimension 0-100 subscores. The composite score is a weighted blend of these. |
| platform_readiness | Yes | Per-engine readiness derived from the dimensions; engines reward different signals. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature, no auth, no rate limits, deterministic rule-based scoring, and headless mode dependencies. These details go beyond annotations (readOnlyHint, idempotentHint, etc.) and add significant behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections and front-loaded information. Slightly verbose but every sentence earns its place. Minor improvement could be achieved by condensing some parameter explanations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, behavior, parameters, usage guidelines, dependencies, and edge cases (robots blocking). Output schema exists, so return values need not be explained. Complete for a complex tool with 5 parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds rich context: explains render modes with performance trade-offs, when to set respect_robots false, and the purpose of generate_report and include_raw_html. This exceeds the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Full AI-SEO audit of a single URL' and lists outputs. It distinguishes from sibling tools by naming them explicitly and positioning this tool as the composite entry point.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'When to use: the default entry point for audit any page' and advises against using individual sub-audit tools unless needed. Provides clear context for when to use headless rendering.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate JSON-LD structured data against Schema.org rules and AI-citation best practices. Accepts either a URL (fetched) or a raw JSON string (parsed directly).
Read-only when given url (one HTTP GET). Zero network when given schema_json. No writes.
Deterministic, rule-based; no LLM. Validates required/recommended properties, @context correctness, sameAs links, and AI-search-friendly patterns.
When to use: focused JSON-LD audits, or to validate a schema block you're about to ship. For a full page audit that includes schema + everything else, use audit_page instead.
Either url or schema_json must be provided (not both). If both are provided, schema_json wins and no fetch happens.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL to fetch and audit. Either this OR `schema_json` is required. Read-only HTTP GET. | |
| schema_json | No | Raw JSON-LD as a string (the contents of a `<script type="application/ld+json">` block). Use this to validate a schema block offline without fetching a URL. Either this OR `url` is required. | |
| respect_robots | No | If true (default), respect robots.txt before fetching `url`. Ignored when `schema_json` is used. |
| Name | Required | Description |
|---|---|---|
| url | Yes | Source URL (null when source=inline). |
| source | Yes | Where the JSON-LD came from. |
| findings | Yes | |
| fetched_at | Yes | |
| found_types | Yes | Schema.org @type values discovered across all JSON-LD blocks. |
| ai_citation_readiness_score | Yes | 0-100 score for the JSON-LD's AI-citation readiness. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds behavioral context: read-only when given url (one HTTP GET), zero network when given schema_json, deterministic and rule-based (no LLM), and conflict resolution (schema_json wins). This adds value beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections and front-loads the main purpose. It uses bullet-like sentences for behavioral points. It is not overly long, but could be slightly more concise (e.g., 'Deterministic, rule-based; no LLM.' is efficient). Overall earns its sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the input schema (3 params, 100% coverage), annotations (readOnly, idempotent, destructive), and existence of an output schema, the description covers all essential aspects: purpose, usage context, behavioral traits, parameter constraints. It provides sufficient context for an AI agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add much beyond schema parameter descriptions, but it clarifies the either-or constraint and the fact that schema_json wins over url. These additions are minor, so score remains at baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates JSON-LD structured data against Schema.org rules and AI-citation best practices. It distinguishes from sibling 'audit_page' by noting that this tool is for focused JSON-LD audits versus full page audits. The verb 'validate' and resource 'JSON-LD schema' are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: 'focused JSON-LD audits, or to validate a schema block you're about to ship.' Also specifies when not to use: 'For a full page audit that includes schema + everything else, use audit_page instead.' Additionally, clarifies that either url or schema_json must be provided, not both, with a win condition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Single-call site sweep: runs audit_page (homepage), check_robots, check_sitemap, and audit_schema in parallel and returns an overall grade (A–F) plus top-5 highest-impact fixes.
Read-only. Issues several HTTP GETs against the domain (homepage fetch, robots.txt, sitemap.xml, and up to 50 sitemap URL HEAD checks); no writes, no auth required, no rate limits beyond polite per-host throttling. The homepage GET is deduplicated across audit_page and audit_schema (~2 network fetches for 4 logical checks). Deterministic, rule-based scoring; no LLM calls. Same domain returns the same grade on repeated runs given unchanged content.
Output: domain, homepage_url, fetched_at, overall_score (0–100), overall_grade, top_5_fixes (Finding[]), and a parts breakdown with individual audit_page, check_robots, check_sitemap, and audit_schema results — each may be a full result or { error: string } when that sub-audit fails.
When to use: quick 'how does this site look overall?' — use when you want a single consolidated score and actionable fix list without calling 4 tools individually. Distinct from audit_sitemap (samples N pages from the sitemap, not just the homepage) and audit_page (single-URL deep dive with all findings, not just top-5).
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Hostname or origin to audit. Examples: `example.com`, `https://example.com`. The tool resolves the homepage and runs audit_page + check_robots + check_sitemap + audit_schema in parallel against it, then returns an overall grade plus top-5 fixes. Issues several HTTP GETs against the domain. | |
| respect_robots | No | If true (default), respect robots.txt before fetching the homepage. Set false ONLY to audit a site you own that has temporarily blocked crawlers. |
| Name | Required | Description |
|---|---|---|
| parts | Yes | Raw sub-audit results, for callers who want to drill in. |
| domain | Yes | |
| fetched_at | Yes | |
| top_5_fixes | Yes | Up to five highest-impact findings across all sub-audits. |
| homepage_url | Yes | |
| overall_grade | Yes | Letter grade derived from the numeric score. |
| overall_score | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, destructiveHint, idempotentHint, openWorldHint. The description adds significant context: 'read-only', 'HTTP GETs', 'no writes, no auth required, no rate limits', 'deduplicated', 'deterministic, rule-based scoring; no LLM calls', and 'same domain returns same grade'. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is comprehensive but well-structured, with key information front-loaded (purpose, behavior, output). Every sentence adds value, though it could be slightly trimmed without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple sub-audits, deterministic scoring, output structure), the description covers input, behavior, output components, and use cases thoroughly. It mentions the output fields (domain, homepage_url, etc.) and sub-audit results, making it complete even without the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description for the 'domain' parameter includes examples, explains the sub-audits run in parallel, and notes that it issues several HTTP GETs. The 'respect_robots' parameter is also well described. This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool as a 'Single-call site sweep' that runs multiple audits in parallel and returns an overall grade and top-5 fixes. It differentiates itself from siblings like audit_sitemap (samples pages from sitemap) and audit_page (single-URL deep dive) with specific verbs and resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides a 'When to use' section: 'quick how does this site look overall?' and distinguishes from alternative tools (audit_sitemap, audit_page). It also states it is read-only and issues HTTP GETs, but could more explicitly mention when not to use it (e.g., when deep multi-page analysis is needed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Site-wide content audit: discovers the sitemap, samples N URLs by deterministic uniform stride, runs audit_page on each, and returns score distribution + worst pages + most-common findings.
Read-only. One HTTP GET for sitemap discovery, optionally a few more for sitemap-index children, then sample_size × audit_page calls (each one HTTP GET + parsing). Polite throttling is enforced per host.
Deterministic — same domain + same sample_size returns the same set of URLs (uniform-stride sampling). Per-page scoring is rule-based; no LLM.
When to use: portfolio-level health check across a site ("how does our content score on average?"). Distinct from audit_site (homepage-only composite) and check_sitemap (validates sitemap.xml structure, not page content).
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Hostname or origin to audit. Examples: `example.com`, `https://example.com`. The tool discovers the sitemap, samples N URLs by uniform stride, and runs audit_page on each. | |
| concurrency | No | Parallel audit_page calls. Default 2 (gentle). Max 5. The shared politeFetch host-delay is still enforced, so this is per-batch dispatch concurrency, not bypass. | |
| sample_size | No | Number of URLs to sample from the sitemap. Default 10. Max 50 (sampling caps to avoid runaway audits — each sample is one full audit_page call, ~1-3s with polite throttling). Sampling is deterministic uniform-stride: if the sitemap has 1000 URLs and sample_size=10, every 100th URL is picked. | |
| respect_robots | No | If true (default), respect robots.txt for each sampled URL. Set false only for self-audits where you've intentionally blocked crawlers. |
| Name | Required | Description |
|---|---|---|
| domain | Yes | The domain audited. |
| failed | Yes | URLs whose audit failed, with the error message. |
| audited | Yes | Per-page audit results that completed successfully. |
| sampling | Yes | Sampling strategy. Deterministic uniform stride: every Nth URL is picked. |
| fetched_at | Yes | UTC ISO-8601 timestamp of the audit. |
| sitemap_url | Yes | Resolved sitemap URL (null when discovery failed). |
| worst_pages | Yes | Lowest-scoring pages from the sample, worst first. |
| top_findings | Yes | Most-common findings across all sampled pages, sorted by occurrence count desc. |
| urls_sampled | Yes | Number of URLs picked via uniform-stride sampling. |
| grade_distribution | Yes | Count of pages per letter grade. |
| score_distribution | Yes | Summary statistics across the audited sample. |
| total_urls_in_sitemap | Yes | Total URLs declared across the sitemap and any indexed children. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), it details read-only nature, HTTP calls, polite throttling, deterministic sampling, and rule-based scoring. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured and front-loaded. Each sentence adds value without redundancy. Summary paragraph, then behavioral details, determinism, and usage guidance in a logical flow.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive coverage of what, how, when, behavioral traits, determinism, safety, and alternatives. Satisfies all needs given complexity and existing annotations/schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 4 parameters. Description adds further context for each, e.g., explaining domain discovery, concurrency throttling, deterministic sampling behavior, and respect_robots purpose.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: discovers sitemap, samples URLs by uniform stride, runs audit_page on each, and returns findings. It uses specific verbs and resources, and distinguishes itself from siblings like audit_site and check_sitemap.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (portfolio-level health check) and contrasts with audit_site (homepage-only) and check_sitemap (structure validation), providing clear guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch and parse a domain's robots.txt; report per-crawler allow/disallow posture for every known AI training crawler (GPTBot, CCBot, Anthropic-AI, Google-Extended, etc.), AI search crawlers (ChatGPT-User, PerplexityBot, OAI-SearchBot), and user-triggered fetchers.
Read-only. One HTTP GET to /robots.txt. No auth, no rate limits applied.
Deterministic, rule-based; no LLM. Returns structured findings with per-crawler status.
When to use: figuring out which AI crawlers a site blocks vs allows. Combine with check_sitemap for a full pre-crawl audit. Distinct from audit_page which evaluates a single URL; this evaluates a whole-domain policy.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Hostname or origin to inspect. Examples: `example.com`, `https://example.com`, `https://example.com/`. The tool fetches `https://<domain>/robots.txt` and reports per-crawler allow/disallow posture for all known AI training crawlers (GPTBot, CCBot, etc.), AI search crawlers (ChatGPT-User, PerplexityBot), and user-triggered fetchers. Read-only HTTP GET to /robots.txt only. |
| Name | Required | Description |
|---|---|---|
| findings | Yes | Per-crawler findings explaining why the posture matters. |
| fetched_at | Yes | UTC ISO-8601 timestamp of the fetch. |
| robots_url | Yes | The robots.txt URL that was fetched. |
| user_triggered | Yes | Allow/disallow posture per user-triggered fetcher (ChatGPT-User, Claude-User, etc.). |
| search_crawlers | Yes | Allow/disallow posture per known AI search crawler (OAI-SearchBot, PerplexityBot, etc.). |
| training_crawlers | Yes | Allow/disallow posture per known AI training crawler (GPTBot, ClaudeBot, CCBot, etc.). |
| recommended_posture | Yes | Suggested posture given the current rules. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint), description adds 'One HTTP GET to /robots.txt. No auth, no rate limits applied. Deterministic, rule-based; no LLM.' No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three paragraphs, each focused. First paragraph defines action and scope, second adds behavioral details, third provides usage guidance. No fluff, but could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given single parameter, annotations, output schema (not shown but indicated), and sibling context, description covers all needed: behavior, use cases, limitations, and contrast.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline 3. Description adds value by listing example domains and known crawlers, and clarifying the fetch URL. Slightly above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Fetch and parse a domain's robots.txt; report per-crawler allow/disallow posture.' Distinct from siblings like check_sitemap and audit_page, as explicitly stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('figuring out which AI crawlers a site blocks vs allows'), suggests combining with check_sitemap, and distinguishes from audit_page.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate a domain's XML sitemap: presence, accessibility, URL count, lastmod freshness, sitemap-index handling, and image/video sitemap extensions.
Read-only. Issues N+1 HTTP GETs: one for robots.txt + sitemap, then up to max_urls_to_check HEADs against sampled URLs.
Deterministic, rule-based; no LLM.
When to use: site-wide indexing audits. Pair with check_robots for a full pre-crawl picture. For per-page checks, use audit_page or check_technical instead.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Hostname or origin to inspect. Examples: `example.com`, `https://example.com`. The tool tries `/sitemap.xml` then the sitemap URL declared in robots.txt; follows sitemap index files one level deep. Read-only HTTP GETs against the domain only. | |
| max_urls_to_check | No | Cap on how many URLs from the sitemap to sample for lastmod, image/video extension, and structural checks. Default 100. Increase up to 500 for large sites where you want a more representative sample; each extra URL is one HTTP HEAD. |
| Name | Required | Description |
|---|---|---|
| domain | Yes | The hostname the sitemap was checked for. |
| status | Yes | Outcome of the sitemap lookup. |
| findings | Yes | |
| fetched_at | Yes | UTC ISO-8601 timestamp of the check. |
| total_urls | Yes | Total URLs declared across the sitemap (and indexed children). |
| sitemap_url | Yes | Resolved sitemap URL (null when status != found). |
| urls_with_lastmod | Yes | Count of URLs that carry a lastmod attribute. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint, idempotentHint, openWorldHint, and destructiveHint. The description adds concrete behavioral details: 'Read-only. Issues N+1 HTTP GETs: one for robots.txt + sitemap, then up to max_urls_to_check HEADs against sampled URLs. Deterministic, rule-based; no LLM.' This goes beyond annotations and provides transparency about network requests and determinism.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (three short paragraphs) and well-structured: purpose first, then behavioral traits, then usage guidelines. Every sentence adds value; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multiple sitemap checks), full parameters, annotations, and the presence of an output schema, the description is complete. It covers what the tool does, how it works, and when to use it, with no missing information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters have descriptions). The description adds extra context: domain parameter notes tool tries /sitemap.xml and follows robots.txt and sitemap indexes; max_urls_to_check explains it caps HTTP HEADs. This adds meaning beyond the schema, justifying a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool validates a domain's XML sitemap, listing specific checks (presence, accessibility, URL count, lastmod freshness, sitemap-index handling, image/video extensions). It uses a specific verb ('Validate') and resource ('domain's XML sitemap'), and distinguishes from siblings like audit_sitemap and check_robots.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool: 'site-wide indexing audits.' It also provides pairings ('Pair with check_robots for a full pre-crawl picture') and alternatives for per-page checks ('use audit_page or check_technical instead').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Audit a page's HEAD section for technical signals relevant to AI crawlers: HTTPS, canonical, OpenGraph, Twitter Card, hreflang, noindex, and title-vs-H1 hygiene.
Read-only. One HTTP GET, inspects HEAD only (body is not parsed).
Deterministic, rule-based; no LLM.
When to use: when you specifically need HEAD-tag audit findings. For the full page including schema and AI-Overview scoring, use audit_page. For canonical-only, use audit_canonical.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public URL to audit. The tool fetches the URL once and inspects HEAD-section signals: HTTPS, canonical, OpenGraph, Twitter Card, hreflang, noindex, title length and overlap with H1. Body content is not parsed. Read-only HTTP GET. | |
| respect_robots | No | If true (default), respect robots.txt before fetching. Set false only for auditing your own site where you've intentionally blocked crawlers. |
| Name | Required | Description |
|---|---|---|
| h1 | Yes | First H1 text. |
| url | Yes | |
| https | Yes | Whether the URL is served over HTTPS after redirects. |
| title | Yes | Page title text. |
| og_url | Yes | OpenGraph og:url, if present. |
| noindex | Yes | Whether meta robots includes noindex. |
| findings | Yes | |
| canonical | Yes | Canonical link href, if present. |
| fetched_at | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses behavioral traits beyond annotations: read-only (one HTTP GET), only inspects HEAD, deterministic/rule-based, no LLM. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four well-structured sentences: purpose, behavioral traits, deterministic nature, usage guidelines. No redundancy, every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity and presence of an output schema, the description provides all necessary context for correct agent selection and invocation, including what is checked and when to use alternatives.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds value by elaborating on the URL parameter's scope (all the signals inspected) and providing context for the `respect_robots` parameter's usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Audit') and resource ('a page's HEAD section for technical signals'), listing the exact signals checked. It distinguishes from siblings by noting what it does not cover, such as schema or full page audits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides a 'When to use' section that specifies the appropriate context (HEAD-tag audit) and names alternative tools (audit_page, audit_canonical) for related but different tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Compare two URLs for AI citation-worthiness and return a structured breakdown of which page is more likely to be cited and why. Typical use: your page (url_a) vs a competitor's page (url_b).
Read-only. Runs audit_page on both URLs in parallel (2 HTTP fetches per URL), then diffs dimension_scores and findings. No new fetch logic beyond what audit_page already does.
Deterministic, rule-based; no LLM calls. Same two URLs return the same comparison on repeated runs.
When to use: competitive gap analysis - understand exactly which dimensions (schema, structure, robots, entity density, freshness, technical, authority, sitemap) put a competitor ahead, and get prioritized fix_recommendations_for_a to close the gap. For a single-URL audit, use audit_page. For overall scoring of one page, use score_citation_worthiness.
Capped at 2 URLs per call. Heuristic verdict - does not claim to know what AI assistants actually cite; verdict matches audit_page's existing rubric.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Optional target search query both pages are competing for (e.g. 'how to connect Zapier to Notion'). When provided, it is surfaced in fix_recommendations_for_a as context. Does not alter the scoring algorithm - scoring is based on audit_page's existing rubric. | |
| url_a | Yes | First URL to compare - typically your own page. Must be a fully-qualified http(s) URL that returns HTTP 200 (redirects are followed). | |
| url_b | Yes | Second URL to compare - typically a competitor's page. Must be a fully-qualified http(s) URL that returns HTTP 200 (redirects are followed). | |
| respect_robots | No | If true (default), respect robots.txt before fetching each URL. Set false only when auditing your own sites where you have intentionally blocked crawlers. |
| Name | Required | Description |
|---|---|---|
| delta | Yes | |
| query | Yes | |
| url_a | Yes | |
| url_b | Yes | |
| scores | Yes | |
| missing_in_a | Yes | |
| missing_in_b | Yes | |
| better_for_citation | Yes | |
| fix_recommendations_for_a | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Adds context beyond annotations: describes parallel execution, deterministic rule-based logic, no LLM calls, 2 URL cap, heuristic verdict. Consistent with readOnlyHint and idempotentHint. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-organized into sections (purpose, behavior, deterministic, when to use, limitations). Slightly verbose but all sentences add value. Front-loaded with key purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With output schema present, return values are covered. Description explains process, limitations, and use cases comprehensively. Annotations provide additional safety context. Complete for a comparison tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters, but description adds useful details: query is optional, url_a/b must be fully-qualified and return 200, respect_robots default and when to override. Adds meaningful value beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compares two URLs for AI citation-worthiness, returning a structured breakdown. It distinguishes from siblings like audit_page (single-URL audit) and score_citation_worthiness (overall scoring), providing a specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly recommends use for competitive gap analysis and tells when not to use: for single-URL audits use audit_page, for overall scoring use score_citation_worthiness. Also gives typical use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Extract named entities, linked concepts, and sameAs graph nodes from a page's content and structured data. Combines body-text NER with JSON-LD @type / sameAs walking.
Read-only when given url (one HTTP GET). Zero network when given text.
Primary path: MCP sampling - the host LLM does the NER and returns typed entities with sameAs URIs. Fallback path: deterministic regex-based extractor when sampling is unavailable. The result includes mode: "sampling" | "regex_fallback" so callers can tell which path ran.
When to use: building an entity map for schema generation, or auditing whether a page's entities match its target topic. To validate the JSON-LD itself, use audit_schema.
Either url or text must be provided.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL to fetch and analyze. Either this OR `text` is required. | |
| text | No | Raw text/HTML to analyze directly. Either this OR `url` is required. | |
| render | No | Rendering mode for `url`. `static` (default) reads raw HTML. `headless` runs Playwright Chromium to capture JS-rendered content (adds 3-10s; requires `playwright-core` + `npx playwright install chromium`). Ignored when `text` is used. | static |
| respect_robots | No | If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| source | Yes | |
| entities | Yes | |
| entity_count | Yes | |
| citation_density_score | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only and non-destructive. The description adds valuable nuance: network behavior differs between 'url' (one HTTP GET) and 'text' (zero network), two execution paths (sampling vs regex fallback) are explained, and the output includes a 'mode' field to indicate which path ran. Dependencies for headless rendering are also noted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the primary purpose and is well-structured into logical sections (overview, paths, when to use). It is longer than ideal but every sentence adds distinct value. Minor redundancy: 'Extract named entities, linked concepts, and sameAs graph nodes' is slightly verbose but acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema (so return values are documented elsewhere) and 4 well-described parameters, the description covers all essential aspects: input conditions, execution modes, dependencies, and use cases. It is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds context beyond the schema: it clarifies the mutual exclusivity of 'url' and 'text' (schema does not mark them required but description explains they are conditionally required), explains the render modes and their implications, and notes that 'respect_robots' is ignored when 'text' is used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb ('Extract') and resource ('named entities, linked concepts, and sameAs graph nodes'), immediately clarifying the tool's core function. It differentiates from sibling 'audit_schema' by stating that tool is for validating JSON-LD itself, not extracting entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'When to use: building an entity map... or auditing whether a page's entities match its target topic.' It also provides an alternative ('To validate the JSON-LD itself, use audit_schema') and clarifies that either 'url' or 'text' must be provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a spec-compliant llms.txt (and optionally llms-full.txt) for a domain by reading its sitemap, sampling up to max_pages pages, and synthesizing a grouped, sectioned summary.
Read-only. Issues one HTTP GET for the sitemap then one per sampled page.
Deterministic; no LLM. Output is the file content as a string - this tool does NOT write to disk or upload anywhere. The caller is responsible for hosting the resulting file at https://<domain>/llms.txt.
When to use: bootstrapping llms.txt for a site you own. To check an existing llms.txt, use llms_txt_validate instead.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Hostname or origin to generate llms.txt for. Examples: `example.com`, `https://example.com`. The tool reads the domain's sitemap, fetches up to `max_pages` of them, and synthesizes a spec-compliant llms.txt grouped by section. Issues N+1 HTTP GETs: one for the sitemap, then one per sampled page. Read-only. | |
| max_pages | No | How many pages to sample from the sitemap when building section groupings. Default 30. Each page is fetched (one HTTP GET per page) - keep this low for large sites or rate-limited hosts. | |
| site_name | No | Override the site name used in the generated llms.txt header. If omitted, inferred from the homepage's <title> tag. | |
| include_full | No | If true, also generate llms-full.txt (the expanded variant containing full page text, not just URLs and titles). Default false. The llms-full.txt output can be large; only enable when you actually plan to host both files. | |
| site_description | No | Override the site description used in the generated llms.txt header. If omitted, inferred from the homepage's meta description. |
| Name | Required | Description |
|---|---|---|
| domain | Yes | |
| llms_txt | Yes | The generated llms.txt file content. Caller is responsible for hosting it. |
| llms_full_txt | No | The generated llms-full.txt content. Null unless include_full=true. |
| pages_indexed | Yes | Number of pages successfully sampled from the sitemap. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds behavioral details beyond annotations: 'Read-only', 'Issues one HTTP GET for the sitemap then one per sampled page', 'Deterministic; no LLM', 'does NOT write to disk or upload anywhere'. No contradiction with annotations (readOnlyHint=true, idempotentHint=true).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is concise, well-structured, and front-loaded with the main action. Every sentence adds value; no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given complexity and presence of output schema, the description fully explains the tool's operation, output format, and caller responsibilities. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but the description adds meaningful context beyond the schema, e.g., explaining the number of HTTP GETs per page and recommending low max_pages for large sites.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a spec-compliant llms.txt for a domain by reading its sitemap, sampling pages, and synthesizing a summary. It distinguishes itself from the sibling tool llms_txt_validate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('bootstrapping llms.txt for a site you own') and when not ('to check an existing llms.txt, use llms_txt_validate instead').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate an existing llms.txt or llms-full.txt against the spec: structure, section ordering, link format, and (optionally) broken-link detection.
Read-only. One HTTP GET when given url; zero network when given content. Optional link-check issues HEAD requests against each link if check_links is true.
Deterministic; no LLM.
When to use: auditing an llms.txt you already have. To generate one from scratch, use llms_txt_generate.
Either url or content must be provided.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL of an existing llms.txt or llms-full.txt to validate (e.g. `https://example.com/llms.txt`). Either this OR `content` is required. | |
| content | No | Raw llms.txt content as a string. Use this to validate a file offline without fetching. Either this OR `url` is required. | |
| check_links | No | If true (default), HEAD each linked URL to detect broken links. Set false to skip link checks for faster, network-light validation of just the structural rules. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| valid | Yes | Whether the file passes structural and link rules. |
| source | Yes | |
| findings | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds key behavioral traits: 'Read-only. One HTTP GET when given url; zero network when given content. Optional link-check issues HEAD requests against each link if check_links is true. Deterministic; no LLM.' This goes beyond the annotations which already declare readOnlyHint and idempotentHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Five sentences, each conveying essential information. No redundant phrases. Front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown but context indicates), the description does not need to detail return values. It covers usage, network behavior, constraints, and alternatives comprehensively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the mutual exclusivity of url and content, and the behavior of check_links (default true).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies 'Validate an existing llms.txt or llms-full.txt against the spec: structure, section ordering, link format, and (optionally) broken-link detection.' It clearly distinguishes from the sibling tool llms_txt_generate, which is for generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'When to use: auditing an llms.txt you already have. To generate one from scratch, use llms_txt_generate.' Also clarifies the requirement that 'Either url or content must be provided.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate a machine-readable /pricing.md for AI shopping/agent flows. Finds the site's pricing page (or uses pricing_url), extracts named tiers and price lines, and returns the file content as a string.
Read-only. Issues a few HTTP GETs probing common pricing paths. Deterministic; no LLM. Does NOT write or upload — the caller hosts the file at https://<domain>/pricing.md.
When to use: a SaaS/e-commerce site that wants agents to read pricing without parsing a JS-rendered table. Falls back to a fill-in template when no prices are detectable.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Hostname or origin to generate pricing.md for, e.g. `example.com`. The tool finds the pricing page (or uses `pricing_url`), extracts tiers and prices, and returns a machine-readable pricing.md string. Read-only. | |
| pricing_url | No | Explicit pricing page URL. If omitted, the tool probes common paths (/pricing, /plans, /pricing/). |
| Name | Required | Description |
|---|---|---|
| domain | Yes | |
| pricing_md | Yes | The generated pricing.md content. Caller hosts it at /pricing.md. |
| source_url | Yes | The pricing page the content was derived from (null when none was found). |
| suggested_path | Yes | |
| tiers_detected | Yes | Number of pricing tiers extracted. |
| validation_issues | Yes | Issues encountered while deriving the file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, idempotentHint, destructiveHint. Description adds behavioral details: read-only, HTTP GETs, deterministic, no LLM, no write/upload. This is valuable context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each purposeful: purpose, behavior details, usage context. No wasted words, well-structured, and front-loaded with primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two parameters and clear annotations, description is complete. Covers what, how, when, and fallback. Output schema exists but not shown; description clarifies return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. Description adds meaning by explaining automatic detection of pricing page, return type (string), and fallback template. Provides significant added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool generates a machine-readable /pricing.md file for AI shopping/agent flows. It specifies the verb 'generate', resource 'pricing.md', and distinguishes from sibling audit/score tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: SaaS/e-commerce sites needing agent-readable pricing. Mentions fallback behavior when no prices are detectable. Could improve by naming alternative tools, but overall clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Render an audit_page or audit_site result as a Markdown report and write it to a file under MCP_WORKSPACE_ROOT (defaults to cwd).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Target file path. May be relative to MCP_WORKSPACE_ROOT (or cwd if unset). Paths that escape the workspace root are rejected. | |
| overwrite | No | If true (default), overwrite an existing file. If false, the write fails when the target already exists. | |
| audit_result | No | The return value of `audit_page` or `audit_site`. Pass the structured result verbatim - the tool detects which shape it is and renders the matching Markdown report. |
| Name | Required | Description |
|---|---|---|
| format | Yes | Which input shape the report was rendered for. |
| saved_to | Yes | Absolute path of the file that was written. |
| bytes_written | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds context about file path restrictions (escapes rejected) and automatic detection of audit result shape. This is useful but not extensive; the core behavioral insight (writes to disk) is already conveyed by the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with the action and outcome. Every word is necessary; no fluff. Perfectly concise for the complexity of the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the three parameters, high schema coverage, and presence of an output schema, the description covers all key aspects: what it does, input requirements (audit_result shape), file path constraints, and overwrite behavior. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by explaining that audit_result should be passed verbatim and that the tool auto-detects its shape. For path, it reiterates the relative-to-root and rejection behavior. This raises the score above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it renders an audit_page or audit_site result as Markdown and writes to a file under MCP_WORKSPACE_ROOT. The verb 'Save' and resource 'audit report to disk' are specific and unambiguous. Among siblings, only this tool performs file I/O, so it's well-distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the tool is used after running audit_page or audit_site, providing clear context. It does not explicitly state when not to use it or mention alternatives, but the sibling tools are all read-only or analysis-focused, making this the sole write operation. A slight nudge toward exclusivity would push this to 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rewrite a content block for Answer Engine Optimization. Adds a BLUF opening, FAQ structure, schema additions, and concise question-shaped headings tuned for ChatGPT / Perplexity / Google AI Overviews.
Read-only when given url (one HTTP GET). Zero network when given text. The tool does NOT write back to the URL - it only returns the rewritten content as a string. No side effects on the source.
This tool delegates the actual rewrite to the calling LLM via MCP sampling - it does not call any external API itself. The MCP host's model produces the rewrite. Same input may produce different output across runs (model-dependent).
When to use: optimizing content for direct-answer surfaces (definitions, how-tos, FAQs). For Generative Engine Optimization (entity-rich, comparison-ready synthesis), use rewrite_geo instead.
Either url or text must be provided. target_query is required.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL whose content should be fetched and rewritten. Either this OR `text` is required. | |
| text | No | Raw content (markdown or HTML) to rewrite directly. Either this OR `url` is required. | |
| format | No | Output shape. `article` for prose-with-headings. `faq` for Q&A list. `howto` for numbered-step procedural content with HowTo schema hints. `comparison` for X-vs-Y tables. Default `article`. | article |
| max_words | No | Soft word budget for the rewrite. Default 1500. Range 100-5000. The rewrite tries to stay under this; very small budgets may force truncation. | |
| target_query | Yes | The user query the rewrite should answer (e.g. `what is RAG`, `how to deploy Ghost to Docker`). Required - drives heading shape and BLUF wording. | |
| respect_robots | No | If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| notes | Yes | Notes from the rewrite (e.g. truncations, format adjustments). |
| format | No | Output format (article, faq, howto, comparison). |
| source | Yes | |
| rewritten | Yes | The rewritten content. The caller decides where to publish it. |
| target_query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description fully explains behavior beyond annotations: read-only when given url (one HTTP GET), zero network when given text, no side effects, delegates to LLM via sampling (no external API), and acknowledges non-idempotence due to model variability. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (8 sentences), well-structured, and front-loaded. Each sentence adds value: purpose, behavior, delegation mechanism, usage guidance, and input requirements. No fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 params, delegation to LLM, output schema exists), the description covers all essential aspects: purpose, behavior, parameter requirements, usage alternatives. The presence of an output schema obviates the need to describe return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions. The description adds value by clarifying the mutual exclusivity of `url`/`text` (not enforced in schema), listing `format` enum examples, and explaining `target_query` drives heading shape and BLUF wording.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The title and description clearly state the tool rewrites content for Answer Engine Optimization, listing specific transformations (BLUF, FAQ, schema, headings) and target AI overviews. It distinguishes from sibling `rewrite_geo` by stating use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use (direct-answer surfaces) and contrasts with `rewrite_geo`. It also specifies that either `url` or `text` must be provided, and `target_query` is required, providing clear practical guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rewrite a content block for Generative Engine Optimization: entity-rich, comparison-ready, synthesis-friendly. Tuned for surfaces that summarize across sources (Perplexity, Google AI Mode, Claude search).
Read-only on input. Does NOT write back to the source URL - returns the rewritten content as a string.
This tool delegates the actual rewrite to the calling LLM via MCP sampling - it does not call any external API itself. The MCP host's model produces the rewrite. Output may vary across runs (model-dependent).
When to use: optimizing for synthesis-style answers across multiple sources. For direct-answer (BLUF + FAQ) optimization on a single page, use rewrite_aeo instead.
Either url or text must be provided. target_query is required.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL whose content should be fetched and rewritten. Either this OR `text` is required. | |
| text | No | Raw content to rewrite directly. Either this OR `url` is required. | |
| max_words | No | Soft word budget. Default 1500. Range 100-5000. | |
| target_query | Yes | The user query the rewrite should answer. Required - drives entity selection and comparison framing. | |
| respect_robots | No | If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used. | |
| add_comparison_table | No | If true, inject an explicit X-vs-Y comparison table into the rewrite (useful for `X vs Y` queries). Default false. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| notes | Yes | Notes from the rewrite (e.g. truncations, format adjustments). |
| format | No | Output format (article, faq, howto, comparison). |
| source | Yes | |
| rewritten | Yes | The rewritten content. The caller decides where to publish it. |
| target_query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint true, openWorldHint true) are consistent. Description adds critical behavioral details: does not write back to source URL, returns string, delegates rewrite to the calling LLM via MCP sampling (no external API call), and output may vary across runs. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured: first sentence captures core purpose, then expands on behavior, usage guidelines, alternative tool, and parameter hints. Every sentence adds value with no redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, 1 required, output schema exists) and richness of annotations, the description covers all necessary aspects: purpose, usage, behavioral transparency, parameter semantics, and alternatives. The existence of an output schema makes return value explanation unnecessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds value by explaining the role of `target_query` in driving entity selection and comparison framing, clarifying the `add_comparison_table` parameter for X-vs-Y queries, and noting mutual exclusivity of `url` and `text`. This exceeds the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool rewrites a content block for Generative Engine Optimization with specific characteristics (entity-rich, comparison-ready, synthesis-friendly). Explicitly distinguishes from sibling tool `rewrite_aeo` by describing different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on when to use (optimizing for synthesis-style answers across multiple sources) and when not to (use `rewrite_aeo` for direct-answer optimization). Also clarifies read-only behavior and delegation to LLM via sampling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score a page against the four signals Google added to the Lighthouse "Agentic Browsing" category in May 2026: presence of an llms.txt, WebMCP integration, accessibility-tree integrity, and layout stability. Returns an overall 0-100 score, a letter grade, and a per-factor breakdown.
Read-only. One HTTP GET for the page plus one for /llms.txt (skip with check_llms_txt=false). Pass html instead of url to score markup offline (llms.txt is then treated as absent).
Deterministic, rule-based heuristics over the fetched HTML; no LLM and no headless render required. This approximates Lighthouse's runtime signals from static markup - it does not execute Lighthouse.
When to use: checking whether a site is ready for AI agents / agentic browsers, or tracking the new Lighthouse Agentic Browsing category. For citation-eligibility of content, use score_citation_worthiness; for a full page audit, use audit_page.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL to fetch and score. Either this OR `html` is required. | |
| html | No | Raw HTML to score offline without fetching. Either this OR `url` is required. llms.txt is treated as absent in this mode. | |
| render | No | Rendering mode for `url`. `static` (default) reads raw HTML; `headless` runs Playwright Chromium (adds 3-10s; requires `playwright-core`). Ignored when `html` is used. | static |
| check_llms_txt | No | If true (default), probe /llms.txt for the host to score the llms.txt factor. Set false to skip that extra HTTP GET. | |
| respect_robots | No | If true (default), respect robots.txt when fetching `url`. Ignored when `html` is used. |
| Name | Required | Description |
|---|---|---|
| url | Yes | The URL scored (null when scoring raw html). |
| grade | Yes | Letter grade derived from the numeric score. |
| score | Yes | Weighted 0-100 Agentic Browsing score (accessibility 40%, layout 35%, webmcp 15%, llms.txt 10%). |
| factors | Yes | The four Lighthouse Agentic Browsing signals, scored 0-100 each. |
| findings | Yes | |
| fetched_at | Yes | UTC ISO-8601 timestamp. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, and no destruction. The description adds significant behavioral context: 'Read-only. One HTTP GET for the page plus one for /llms.txt... Deterministic, rule-based heuristics... no LLM and no headless render required.' It also clarifies limitations (approximates Lighthouse, does not execute it). No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It opens with a clear purpose statement, then provides detailed behavior, parameter guidance, and usage context. Every sentence adds value with no redundancy. The final paragraph succinctly covers when to use and alternatives.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (5 parameters, output schema exists), the description covers all necessary aspects: purpose, behavioral details, parameter semantics, usage guidelines, and sibling differentiation. The existence of an output schema means return values need not be detailed. The description is fully satisfactory.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value beyond schema by explaining parameter interactions, e.g., 'Pass html instead of url to score markup offline (llms.txt is then treated as absent)' and 'Set false to skip that extra HTTP GET' for check_llms_txt. This contextual guidance elevates it above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Score a page against the four signals Google added to the Lighthouse Agentic Browsing category.' It specifies the verb (score), resource (page), and the specific signals. It distinguishes from siblings by directly naming alternatives like score_citation_worthiness and audit_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides usage guidance: 'When to use: checking whether a site is ready for AI agents / agentic browsers, or tracking the new Lighthouse Agentic Browsing category.' It also lists alternative tools for different tasks, clearly defining when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score a page's probability of appearing in Google AI Overviews. Returns an overall 0-100 score plus six factor subscores: semantic completeness, structured data, E-E-A-T signals, entity density, freshness, and technical hygiene.
Read-only. One HTTP GET.
Deterministic, rule-based scoring derived from published 2025-2026 AI-Overview correlation studies. No LLM calls. Same URL returns the same score on repeated runs.
When to use: AI-Overview-specific prioritization. For a multi-dimensional audit that includes this scoring plus everything else, use audit_page. For citation-worthiness of a specific text passage (rather than a URL ranking probability), use score_citation_worthiness.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Public URL to score. The tool fetches the URL once and runs deterministic, rule-based scoring across six factors (semantic completeness, structured data, E-E-A-T signals, entity density, freshness, technical hygiene) using published 2025-2026 correlation studies. No LLM calls. Read-only HTTP GET. | |
| respect_robots | No | If true (default), respect robots.txt before fetching. Set false only for auditing your own site where you've intentionally blocked crawlers. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| factors | Yes | Per-factor 0-100 subscores. |
| fetched_at | Yes | |
| top_improvements | Yes | |
| overall_eligibility_score | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond annotations (readOnlyHint, idempotentHint, destructiveHint), the description adds key traits: 'Read-only. One HTTP GET.', 'Deterministic, rule-based scoring... No LLM calls.', 'Same URL returns the same score on repeated runs.' No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-structured: purpose first, then output details, then behavioral traits, then usage guidance. Every sentence adds unique value with no redundancy. Front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters with full schema coverage, an output schema (mentioned), and annotations covering safety, the description is complete. It explains what the tool does, what it returns (overall score + six subscores), and how to choose it over siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters documented). The main description adds value by explaining the URL parameter's behavior ('fetches the URL once and runs deterministic...') and providing usage guidance for respect_robots ('Set false only for auditing your own site where you've intentionally blocked crawlers.').
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Score') and resource ('page's probability of appearing in Google AI Overviews'). It distinguishes from siblings by naming audit_page and score_citation_worthiness as alternatives for different use cases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use ('AI-Overview-specific prioritization') and when not, with named alternatives: 'use audit_page' for multi-dimensional audit, 'use score_citation_worthiness' for passage citation-worthiness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Score how citable a page or text block is for AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews). Evaluates BLUF (bottom-line-up-front) opening, FAQ patterns, statistic density, entity clarity, and answer-shape fit for the optional target_query.
Also returns extractability_score plus per-section chunk_analysis: how cleanly an LLM can lift a self-contained answer from each heading-delimited section (length band, lead-sentence directness, anaphora, concrete anchors). This is the GEO mechanic - it pinpoints the exact sections to tighten, with most_extractable / least_extractable called out.
Read-only when given url (one HTTP GET). Zero network when given text. No writes.
Deterministic, rule-based; no LLM calls. Returns reproducible scores.
When to use: pre-publish content QA, or to triage which existing pages are worth optimizing for AI citation first. Distinct from score_ai_overview_eligibility which scores Google-AI-Overview ranking probability for a URL; this scores the inherent citability of a text passage regardless of host.
Either url or text must be provided.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL to fetch and score. Either this OR `text` is required. | |
| text | No | Raw text/markdown/HTML to score directly without fetching. Either this OR `url` is required. | |
| target_query | No | Optional target search query the content is supposed to answer (e.g. `how to fix CORS errors in Next.js`). When provided, scoring weights answer-shape fit and query-term coverage. Omit if you want a query-agnostic citability score. | |
| respect_robots | No | If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used. |
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| source | Yes | |
| signals | Yes | Per-signal subscores (bluf, faq, stats, entities, etc.). |
| suggestions | Yes | |
| target_query | Yes | |
| engine_scores | Yes | |
| overall_score | Yes | |
| chunk_analysis | No | Per-section extractability: how cleanly an LLM can lift a standalone answer from each chunk. |
| most_extractable | No | |
| least_extractable | No | |
| extractability_score | No | Length-weighted mean of per-section extractability scores. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it specifies read-only behavior ('one HTTP GET' for url, 'zero network' for text), confirms no writes, and emphasizes determinism and reproducibility. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is fairly concise given the complexity of the tool. It is well-structured with an initial summary, then details on evaluation factors, behavioral notes, usage guidelines, and sibling distinction. Every sentence provides useful information, though it could be slightly tightened.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage, behavior, and parameter semantics adequately. It does not address edge cases (e.g., handling of both url and text simultaneously, or fetch failures), but the presence of an output schema and annotations means not all details must be in the description. It provides sufficient context for correct tool selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, baseline is 3. The description adds value by explaining the mutual exclusivity of url and text, and by specifying that target_query influences scoring (answer-shape fit, query-term coverage) when provided. This goes beyond the schema's field descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool scores citation worthiness for AI engines, lists specific evaluation factors (BLUF, FAQ, etc.), and explicitly distinguishes itself from the sibling tool score_ai_overview_eligibility by contrasting what each tool measures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage contexts: 'pre-publish content QA' and 'triage which existing pages are worth optimizing for AI citation first.' It also notes that either url or text must be provided. However, it does not explicitly state when NOT to use the tool or provide direct alternatives beyond the one sibling mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Simulate would an AI engine cite this page for this query?. The host LLM role-plays the chosen engine (chatgpt / claude / perplexity / google_ai_overviews / any), reads the page content, and returns a cite/no-cite verdict with the verbatim excerpt it would surface plus ranked improvements.
Read-only when given url (one HTTP GET). Zero network when given text.
Primary path uses MCP sampling. If the host doesn't support sampling, falls back to a deterministic heuristic derived from score_citation_worthiness (overall_score + per-engine subscore must both clear thresholds). The result includes mode: "sampling" | "static_heuristic" so callers can tell which path ran.
When to use: pre-publish gut-check for a specific query, or auditing whether existing content earns citation surface. Distinct from score_citation_worthiness (deterministic 0-100 score) and audit_page (whole-page rubric); this returns a binary cite/no-cite verdict tied to one query.
Either url or text must be provided. target_query is required.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Public URL to fetch and test. Either this OR `text` is required. | |
| text | No | Raw text/HTML to test directly. Either this OR `url` is required. | |
| engine | No | Which engine to simulate. `any` (default) uses a generic AI-search persona. Specific engines tune the cite criteria (e.g. perplexity favors statistic-dense excerpts; google_ai_overviews favors schema + freshness). | any |
| target_query | Yes | The user query the engine is answering. Required. Example: `how to add JSON-LD to a Next.js app`. | |
| respect_robots | No | If true (default), respect robots.txt when fetching `url`. Ignored when `text` is used. |
| Name | Required | Description |
|---|---|---|
| mode | Yes | Which code path produced the result: MCP sampling (host LLM) or deterministic heuristic fallback. |
| engine | Yes | Which engine persona produced the verdict. |
| reasoning | Yes | Plain-language explanation of the verdict. |
| confidence | Yes | How likely a real engine is to surface this page (0-100). |
| would_cite | Yes | Binary verdict: would the simulated engine cite this page for the query? |
| improvements | Yes | Ranked, specific edits to improve citation probability. |
| target_query | Yes | The query the engine simulation answered. |
| blocking_issues | Yes | Concrete reasons the page is (or is not) citable. Empty if would_cite=true and excerpt is clearly attributable. |
| citation_excerpt | Yes | If would_cite=true, the 20-60 word verbatim excerpt the engine would surface; otherwise null. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature (one HTTP GET for url, zero network for text), the fallback to heuristic if sampling is unsupported, and the mode indicator in results. Adds significant value beyond annotations by explaining the dual execution paths.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with front-loaded main purpose. Every sentence adds value, covering fallback, usage, and parameters. Could be slightly shorter, but not wasteful. Good balance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the simulation logic, fallback mechanism, engine simulation, and output contents (verdict, excerpt, improvements, mode). With an existing output schema, this is fully complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds meaning by explaining engine-specific tuning (e.g., perplexity favors statistic-dense excerpts), the mutual exclusivity of url and text, and the effect of respect_robots. This justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it simulates whether an AI engine would cite a page, returning a cite/no-cite verdict with an excerpt and improvements. It distinguishes from sibling tools like score_citation_worthiness and audit_page by specifying the binary verdict tied to a single query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: pre-publish gut-check for a specific query or auditing citation surface. Also implies when not to use by contrasting with deterministic scoring and whole-page rubric. Provides clear context and alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
audit_canonicalaudit_pageaudit_schemaaudit_siteaudit_sitemapcheck_robotscheck_sitemapcheck_technicaldiff_pagesextract_entitiesllms_txt_generatellms_txt_validatepricing_generatereport_saverewrite_aeorewrite_geoscore_agentic_browsingscore_ai_overview_eligibilityscore_citation_worthinessscore_test_citation
Add one secure layer between your agents and this server.