AI-SEO / AEO / GEO Audit

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered structurally. The description still adds real behavioral context beyond that: a single HTTP GET, HEAD-only parsing, and deterministic rule-based evaluation with no LLM. It stops short of describing failure modes (unreachable URL, redirect chains) or any rate-limit behavior.

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 short paragraphs, zero padding: scope first, then execution model, then routing guidance. Every sentence carries information an agent would otherwise have to infer.

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?

An output schema exists, so return-value explanation is correctly omitted. For a 2-param read-only audit tool, the description covers scope, cost (one GET), execution model (deterministic, HEAD-only), and sibling routing — nothing material is missing.

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 both parameters (url, respect_robots) are already fully documented in the schema, including redirect-following, HEAD-only inspection, and the robots.txt override case. The description adds no parameter-level detail beyond that, so the baseline 3 applies.

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?

Specific verb+resource ('Audit a page's canonical link integrity') followed by an enumerated scope (presence, self-reference, cross-domain mismatches, trailing-slash hygiene, og:url consistency). It explicitly distinguishes itself from the nearest siblings (check_technical, audit_page), so an agent can route without opening a schema.

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?

Explicit 'When to use' clause with a concrete scenario (debugging duplicate-content), plus named alternatives for adjacent needs: check_technical for a full HEAD audit and audit_page for everything-on-a-page. Both the when and the when-not are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/openWorld/idempotent/non-destructive, but the description goes well beyond them: it discloses the exact network behavior per mode (one HTTP GET for url, zero network for schema_json), that it is deterministic/rule-based with no LLM, and what it validates. This is genuinely additive 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?

Front-loads the core purpose, then behavior, then usage routing in short scannable sentences. Every sentence carries new information with no restatement of the name or schema.

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?

Inputs, mode-specific behavior, precedence rules, and sibling routing are all covered; an output schema exists so return values need not be described. Nothing an agent needs to invoke this correctly is missing.

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 the baseline is 3. The description adds meaning the schema does not: mutual exclusivity of url/schema_json and, critically, the precedence rule that schema_json wins and no fetch occurs when both are supplied.

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?

States a specific verb (validate) and resource (JSON-LD structured data) with scope (Schema.org rules, AI-citation best practices). It explicitly distinguishes itself from the sibling audit_page, so an agent can choose correctly without opening any schema.

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 an explicit 'When to use' line, names the alternative (audit_page) and the condition that selects it (full page audit), and explains the url-vs-schema_json input selection. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already cover read-only, idempotent, open-world, and non-destructive behavior, but the description adds substantive context beyond them: the N+1 HTTP GET pattern, HEAD sampling against up to max_urls_to_check URLs, one-level sitemap-index traversal, and that the logic is deterministic/rule-based with no LLM. It stops short of stating rate limits, timeout, or failure semantics for an unreachable sitemap.

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 tight blocks with zero filler: what it checks, how it behaves on the network, and when to use it. The routing information is front-loaded and no sentence is redundant.

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?

An output schema exists, so return values need not be described, and the description covers behavior, request pattern, and usage routing adequately for a two-parameter read-only tool. The one real hole is the unresolved overlap with the sibling `audit_sitemap`, which an agent cannot resolve from this text.

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% and both parameters are fully documented in the schema, including examples for `domain` and the default/max semantics of `max_urls_to_check`. The description adds no parameter meaning beyond that, so the baseline 3 applies.

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?

States a specific verb (validate) and resource (XML sitemap) and enumerates exactly what is checked: presence, accessibility, URL count, lastmod freshness, sitemap-index handling, and image/video extensions. It distinguishes itself from check_robots, audit_page, and check_technical, but never addresses the near-identical sibling `audit_sitemap`, which is the one an agent is most likely to confuse it with.

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?

Explicit 'When to use: site-wide indexing audits' plus a named companion tool (check_robots) and named alternatives for per-page checks (audit_page, check_technical). No exclusions are given relative to audit_sitemap, so the agent is left to guess between two sitemap tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, openWorld, and non-destructive, so safety is covered. The description adds real context beyond that: it performs exactly one HTTP GET, inspects HEAD only and does not parse the body, and is deterministic rule-based with no LLM involvement. It does not mention rate limits or timeouts, so it stops short of a 5.

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?

Front-loaded with what gets audited, followed by short scoping lines for behavior and routing. Every sentence carries distinct information; no filler.

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?

An output schema exists, so return values need not be explained. Behavior, scope, method, and sibling routing are all present; nothing an agent needs to call this correctly is missing.

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 both parameters (url, respect_robots) are already documented in the schema, including the robots.txt default semantics. The description adds no syntax or format detail beyond that, so the baseline 3 is appropriate.

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?

States a specific audit verb on a specific resource (a page's HEAD section) and enumerates the exact signals inspected: HTTPS, canonical, OpenGraph, Twitter Card, hreflang, noindex, title-vs-H1. This is clearly distinguishable from siblings like audit_page and audit_canonical.

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?

Explicit when-to-use clause plus two named alternatives with their selecting conditions ('For the full page including schema and AI-Overview scoring, use `audit_page`. For canonical-only, use `audit_canonical`'). Routing is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses traits beyond annotations: read-only vs zero-network depending on input mode, the sampling-primary/regex-fallback dual execution path, and the mode field in the result so callers know which path ran. Annotations cover safety hints but not the sampling/fallback behavior or network semantics per input.

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?

Front-loaded with the core action and mechanism, then structured into behavioral, when-to-use, and constraint paragraphs. Slightly dense with parenthetical asides but every sentence carries information; no filler.

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 an output schema present, it needn't explain return values, yet it still flags the mode field callers rely on. Network behavior, sampling vs fallback, alternatives, and the input constraint are all covered, making it complete for a 4-param read 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 description coverage is 100%, so the schema already documents url, text, render, and respect_robots fully including defaults, enum values, and headless timing. The description reinforces the url-or-text rule but adds no parameter detail 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?

States a specific verb (extract) and resources (named entities, linked concepts, sameAs graph nodes) plus the two input sources. Explicitly distinguishes itself from sibling audit_schema by naming it and describing the different scope.

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?

Gives two concrete when-to-use cases (building entity maps for schema generation, auditing entity-topic match) and names the alternative tool for a related-but-different job (audit_schema). Also states the url-vs-text selection rule and the input requirement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnly/idempotent/openWorld, but the description adds the actual cost model: one HTTP GET when given url, zero network when given content, HEAD requests per link when check_links is true, and explicitly 'no LLM'. This is exactly the kind of context annotations cannot express.

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 short paragraphs, each front-loaded with its topic (what it validates, network behavior, when to use). No filler; every clause carries 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?

Covers validation scope, network/auth implications, determinism, sibling routing, and the parameter constraint. With an output schema present, return values need not be explained. Nothing an agent needs is missing.

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 already 100%, so the baseline is 3. The description adds the mutual-exclusivity rule ('Either url or content must be provided') and confirms the network-side effect of check_links beyond what the schema's own description states. Marginal value, but real.

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?

States a specific verb (validate) and resource (llms.txt or llms-full.txt), and enumerates exactly what dimensions are checked: structure, section ordering, link format, broken links. It also explicitly distinguishes itself from the sibling llms_txt_generate by naming that tool.

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?

Explicit 'When to use: auditing an llms.txt you already have' plus a routing rule to the alternative ('To generate one from scratch, use llms_txt_generate'). No inference needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well past the annotations: it discloses that the url path performs exactly one HTTP GET, that the text path makes zero network calls, that nothing is written back to the source, and that the rewrite is delegated to the calling LLM via MCP sampling so output is non-deterministic across runs. The idempotentHint=false annotation is now explained rather than merely asserted.

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?

Purpose and mechanism are front-loaded, then network behavior, then routing guidance, then input constraints - a sensible order. Every sentence carries information, though the network/side-effect paragraph is slightly repetitive ('does NOT write back', 'No side effects on the source').

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 6-parameter, open-world rewrite tool with an output schema present, the description covers what an agent needs: transformation scope, network/side-effect profile, non-determinism, input requirements, and sibling routing. Return-value explanation is correctly omitted since the output schema exists.

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, but the description adds a genuine cross-parameter constraint the schema does not encode: 'Either `url` or `text` must be provided' (required is only `target_query`). It also confirms target_query drives heading shape and BLUF wording, which explains why it is required rather than just restating it.

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?

States a specific verb and resource ('Rewrite a content block for Answer Engine Optimization') and immediately enumerates the concrete transformations (BLUF opening, FAQ structure, schema additions, question-shaped headings). It also names the sibling it is not (`rewrite_geo`), so an agent can separate the two rewrite tools without opening either schema.

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 an explicit when-to-use clause ('optimizing content for direct-answer surfaces (definitions, how-tos, FAQs)') plus an explicit alternative with its own selection condition ('For Generative Engine Optimization ... use `rewrite_geo` instead'). Input prerequisites are also stated ('Either `url` or `text` must be provided. `target_query` is required').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=false and openWorldHint=true; the description goes further by disclosing that no write-back occurs, that the rewrite is delegated to the host LLM via MCP sampling rather than an external API, and that output varies across runs. These are behavioral facts the annotations cannot express.

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?

Front-loads what the tool does, then the read-only/no-write-back guarantee, then the non-obvious sampling behavior, then usage guidance. Mostly tight, though the sampling/determinism paragraph could be compressed into fewer words without loss.

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?

An output schema exists so return-value explanation is unnecessary; the description instead covers the non-obvious execution model (host LLM sampling), determinism caveat, read-only semantics, and sibling routing. Nothing an agent needs to invoke it correctly is missing.

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 all six parameters (url, text, max_words, target_query, respect_robots, add_comparison_table) are already documented in the schema. The description only restates the either/or url-vs-text rule and target_query requirement, adding no syntax or format detail 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?

States a specific verb (rewrite) and resource (content block) plus the optimization target (GEO), and explicitly names the sibling it is not (`rewrite_aeo`). An agent can distinguish it from the AEO variant without opening either schema.

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 an explicit 'When to use' clause tied to synthesis-style optimization and routes the agent to `rewrite_aeo` for direct-answer/BLUF+FAQ optimization. The alternative and the condition selecting it are both stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, open-world, idempotent, non-destructive behavior. The description adds meaningful context beyond annotations: one HTTP GET, deterministic rule-based scoring from published 2025-2026 studies, no LLM calls, and identical results for the same URL on repeated runs.

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 purpose and return format, then concisely states read-only behavior and deterministic scoring. It closes with explicit usage routing, with no wasted 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 tool's complexity, full parameter coverage, annotations, and presence of an output schema, the description provides everything an agent needs to select and invoke it correctly. The return-value summary is extra but not harmful.

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 both parameters are already well documented in the input schema. The description does not add parameter-specific meaning beyond what the schema provides, so the baseline of 3 is appropriate.

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 and resource: score a page's probability of appearing in Google AI Overviews. It also distinguishes itself from siblings by naming `audit_page` and `score_citation_worthiness` with the conditions that select them.

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?

It gives explicit when-to-use guidance: AI-Overview-specific prioritization. It also routes to two alternatives with clear conditions: `audit_page` for a broader audit including this scoring, and `score_citation_worthiness` for text passage citation-worthiness rather than URL ranking probability.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive and open-world, so the safety bar is covered. The description still adds genuine value beyond them: the network profile is parameter-contingent ('one HTTP GET' with url, 'zero network' with text) and it states the engine is deterministic and rule-based with no LLM calls, yielding reproducible scores.

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?

Front-loads the core purpose, then progressively details the mechanic (chunk_analysis), runtime behavior, and routing. Every sentence carries information, though the section list and the extractability paragraph are dense enough to nudge past ideal brevity.

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?

An output schema exists, yet the description still orients the agent by naming the returned fields (extractability_score, per-section chunk_analysis, most_extractable/least_extractable). With the url/text requirement, usage scenarios, and sibling differentiation all present, nothing an agent needs to call it correctly is missing.

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 nonetheless sharpens parameter meaning: `text` is characterized as the zero-network path, `url` as the one-GET path, and `target_query` is the query that reweights answer-shape fit. Only `respect_robots` goes unmentioned in prose, keeping this just short of a 5.

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?

States a specific verb+resource ('Score how citable a page or text block is for AI engines') and enumerates the exact dimensions scored (BLUF, FAQ patterns, statistic density, entity clarity, answer-shape fit). It explicitly names the sibling it is not, `score_ai_overview_eligibility`, and differentiates on host-independence.

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?

Gives concrete when-to-use scenarios ('pre-publish content QA, or to triage which existing pages are worth optimizing for AI citation first') and an explicit alternative with the selecting condition ('this scores the inherent citability of a text passage regardless of host').

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.