mcp-seo

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the description's behavioral transparency adds 'No file modifications' and 'diagnostic evaluation' – specific context that reinforces but goes slightly beyond the annotation. It aligns without contradiction, so not a perfect 5 but above the baseline given the annotation coverage.

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 efficiently organized into three clear sections: purpose, usage guidelines, and behavioral transparency. Every sentence contributes value, with no redundancy or fluff. It is front-loaded with the primary purpose and exclusions early.

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 single-parameter tool with annotations covering safety, the description thoroughly explains what it audits (specific AEO elements), when to use it, and explicitly excludes other audit types. No output schema exists, but the evaluation criteria are enumerated, making the tool's function fully understandable.

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% for the single 'target' parameter, which already explains URL or file path. The description does not add parameter-specific details, so it relies on the schema. This meets the baseline for high coverage, but no extra semantic value is provided by the description itself.

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 verb 'Audits' and the resource 'content for AEO', listing specific evaluation criteria (direct answer blocks, question-based subheadings, FAQ schema, citation readiness). It differentiates from siblings by explicitly naming seo_audit_geo and seo_audit_onpage in usage guidelines, making its scope unmistakable.

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 USAGE GUIDELINES section explicitly states when to use the tool (optimizing for conversational AI citations, direct answers, Perplexity) and provides two explicit 'Do NOT use' exclusions with alternative tool names (seo_audit_geo, seo_audit_onpage). This leaves no ambiguity about 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description's 'Safe, read-only content analysis. No file modifications' largely restates the annotations with only marginal added context ('No file modifications'). It adds some value but not rich behavioral disclosure beyond what annotations provide.

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 main purpose is front-loaded in the first sentence, and the USAGE GUIDELINES and BEHAVIORAL TRANSPARENCY sections are short and purposeful. Slight redundancy exists where the behavioral section repeats annotation data, but overall structure is clean and efficient.

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 read-only analysis tool with a single, fully-documented parameter and safety annotations, the description covers what the tool audits, when to use it, and what to avoid. No output schema exists, but that is not a requirement for an audit tool. The only minor gap is that it doesn't describe the shape of the returned audit report, but this is acceptable given the audit context.

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% — the target parameter already carries a full description ('Target live URL or local file path to audit'). The tool description adds no parameter-level detail beyond the schema, so the baseline of 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?

The description opens with a specific verb ('Evaluates') and a well-scoped resource (article/landing page content), listing concrete audit dimensions: content depth, search intent classification, word count thresholds, thin-content risks, reading ease, and E-E-A-T signals. This clearly distinguishes it from siblings like seo_audit_schema or seo_audit_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?

A dedicated USAGE GUIDELINES section states both when to use the tool (article/landing page editorial quality and intent alignment) and explicitly what not to use it for, naming two alternatives (seo_audit_schema and seo_generate_marketing_strategy). This is textbook when/when-not guidance with concrete alternatives.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a clear 'Safe, read-only CRO analysis. No file modifications' statement, reinforcing the annotation without contradicting it. It doesn't add details about rate limits or output format, but for a read-only audit tool the behavioral disclosure is adequate.

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 compact and front-loaded: the core purpose appears in the first sentence, followed by a scoped list of audit elements, then usage and behavior sections. Every sentence earns its place with 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?

For a single-parameter read-only audit tool with full schema coverage and no output schema, the description covers purpose, scope, usage boundaries, and safety. It doesn't describe the return format, but since there is no output schema and the tool is an audit, an agent can reasonably expect a report; this is a minor gap rather than a critical omission.

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 single 'target' parameter is fully documented in the schema. The description adds context about what the audit evaluates but doesn't add new parameter-level meaning beyond the schema. 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?

The description states a specific verb ('Audits') and resource ('Conversion Rate Optimization (CRO) and user conversion signals'), then enumerates concrete elements (CTAs, contact channels, social proof, mobile buttons, risk reversal). This clearly distinguishes it from sibling SEO audit tools focused on on-page, technical, or content signals.

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 (landing pages, pricing pages, checkout/contact funnels) and when not to use (organic ranking signals), naming the alternative tools 'seo_audit_onpage' and 'seo_audit_technical'. This is exactly the kind of routing guidance an agent needs.

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, idempotentHint=true, destructiveHint=false. The description adds context by stating it is a 'Safe, read-only diagnostic evaluation' and 'No file modifications,' reinforcing the safety profile. It also specifies the audit scope, which is useful but not strictly necessary beyond 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?

The description is concise and well-structured with clear sections: purpose, usage guidelines, and behavioral transparency. Every sentence adds value, and the most important information (what the tool does) is front-loaded.

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 read-only audit tool with a single parameter and no output schema, the description provides a thorough overview of the audit's scope, distinguishes it from related tools, and states its safety. Nothing essential for an agent to decide whether to invoke it 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% for the single parameter 'target', so the schema already fully documents its format. The description adds no additional parameter-level detail, so it does not exceed the baseline expected when schema coverage is high.

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 audits Generative Engine Optimization (GEO) and lists specific evaluation areas (brand entities, Schema.org definitions, sameAs reconciliation, E-E-A-T credentials). It explicitly names sibling tools it is not, providing strong differentiation.

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 gives explicit when-to-use guidance ('Use to evaluate how LLM-based search engines comprehend brand identity and authority') and provides two clear exclusions with alternative tool names (seo_audit_local, seo_audit_aeo). This leaves no ambiguity for an agent.

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=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds value by explicitly calling it a 'Safe, read-only link graph analysis' and stating 'No file modifications,' reinforcing and slightly extending the annotations. No contradiction found.

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 a concise overview followed by brief usage and behavior sections. Every sentence adds actionable information with no filler or repetition of the 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?

For a single-parameter, read-only audit tool with rich annotations, the description adequately covers what the tool does and how it should be used. It does not detail the exact return format, but no output schema is expected and the described outputs (anchor text, orphan flags, link suggestions) sufficiently imply the shape of results.

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 the single target parameter is already well documented in the schema. The description does not add parameter-specific detail beyond the schema, which is acceptable; 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?

The description opens with a specific verb ('Audits internal linking structure') and enumerates concrete capabilities: identifying generic anchor text, flagging orphan pages, and suggesting contextual links. This clearly distinguishes it from the other seo_audit_* siblings without needing to open their schemas.

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 has an explicit USAGE GUIDELINES section that states when to use the tool ('improve PageRank flow, internal topic clustering...') and an explicit exclusion with a named alternative ('Do NOT use to inspect external backlink profiles; use seo_suggest_related_ecosystem'). This is ideal routing guidance.

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, idempotentHint, and destructiveHint=false. The description reinforces this with 'Safe, read-only diagnostic evaluation. No file modifications.' It adds the word 'diagnostic' which clarifies the nature of the operation, though it largely restates the annotations. It does not contradict annotations and provides a small additional 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?

The description is well-structured with clear sections (purpose, usage guidelines, behavioral transparency), front-loads the core function, and every sentence adds value. It is concise without being overly terse, making it easy for an agent to quickly grasp the tool's role.

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 tool with one fully-documented parameter and rich annotations, the description covers its purpose, scope, and usage exclusions comprehensively. It does not need to describe return values since there is no output schema, and it provides enough behavioral context for an agent to decide 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% for the single parameter 'target', which is described as 'Target live URL (e.g. "https://example.com/chicago") or local file path to audit.' The description does not add extra parameter semantics beyond this, but since the schema fully covers it, a 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 clearly states the tool audits Local and Area SEO and enumerates specific elements it evaluates: LocalBusiness Schema.org JSON-LD, NAP consistency, click-to-call links, Google Maps embed signals, and doorway city page duplication. This gives a precise verb-resource pairing and distinguishes it from sibling audit tools by its local focus.

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 usage context is provided: use for local business websites, multi-location practices, and regional service providers, and explicitly excludes pure SaaS, digital-only, or non-geographic sites with named alternatives ('seo_audit_technical' or 'seo_audit_onpage'). This leaves no ambiguity about when to select 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 readOnlyHint, idempotentHint, and destructiveHint; the description reinforces this with 'Safe, read-only diagnostic evaluation' and adds 'No file modifications.' This clarifies the exact operational effect beyond the schema, though it does not discuss auth or rate limits.

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 compact, front-loads the core purpose, and uses clearly labeled sections for usage and behavior. Every sentence adds actionable information without 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?

For a single-parameter read-only audit tool, the description covers what is checked, when to use it, what not to use it for, and the target format. No output schema exists, so a brief note on expected return values would make it fully complete, but this is a minor gap.

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?

The schema already fully documents the single 'target' parameter at 100% coverage as a live URL or local file path. The description does not need to add parameter detail, so it is correctly at the baseline for high schema coverage.

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 ('Audits') and a clear resource: on-page SEO elements, and enumerates the exact checks: title tag length/keyword placement, meta description CTR, H1 enforcement, hierarchy, OpenGraph, and Twitter cards. This distinguishes it from sibling audit tools by naming the on-page 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?

Contains explicit 'Use when' guidance for page-level metadata, heading structures, and social previews, followed by two 'Do NOT use' exclusions that name alternatives (seo_audit_technical, seo_audit_schema). An agent can confidently route between siblings.

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, and idempotentHint=true. The description reinforces these with 'Safe, read-only performance diagnostic' and 'No file modifications', and adds the crucial behavioral detail that it performs 'static source code analysis' rather than live browsing. This adds context beyond the annotations without contradicting them.

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 (description, usage, behavioral transparency), front-loads the core purpose, and every sentence carries meaningful information. 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?

For a single-parameter, read-only tool with no output schema, the description covers purpose, usage, and safety thoroughly. The only minor gap is that it doesn't explicitly describe what the audit returns (e.g., a report format), but given the sibling tools and the nature of audits, this is a reasonable assumption. Overall, it is sufficiently complete for an agent to call it 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% (the sole parameter 'target' is clearly documented as a URL or file path). The description does not add additional parameter-specific details, but the baseline of 3 is appropriate since the schema already covers it adequately.

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 ('Identifies') and a specific resource ('code-level Core Web Vitals risks'), enumerating concrete defect types (CLS from images, LCP from formats, render-blocking scripts). This clearly distinguishes it from sibling audit tools (e.g., seo_audit_technical, seo_audit_onpage) by focusing exclusively on performance metrics.

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 'USAGE GUIDELINES' section provides a clear 'Use to' directive and a 'Do NOT use' exclusion, explicitly naming Lighthouse as the alternative for real-time browser benchmarks. This leaves no ambiguity about when to select 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 provide readOnly, idempotent, and non-destructive hintscanonical_for_relation:

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 organized into three concise labeled sections with no filler. The primary purpose is front-loaded, usage guidance and behavior are clearly separated, and every sentence earns its place.

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 single-parameter, read-only audit tool, the description covers purpose, resource scope, usage boundaries, alternatives, and safety behavior. An agent has everything needed to select and invoke it correctly, even though no 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?

The only parameter, target, is already fully described in the schema as a website URL or local codebase folder path, giving 100% schema description coverage. The tool description itself does not add parameter-specific guidance, so the baseline score 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 leads with a specific verb ('Inspects') and names concrete resources: robots.txt rules per user-agent, sitemap index validity, contradictory directives, and HTTP security headers. This clear enumeration of scope goes beyond the tool name and distinguishes it from body-crawling sibling 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 the tool: inspect crawl configuration and indexation guardrails for Googlebot, GPTBot, ClaudeBot, and PerplexityBot. It also gives a clear exclusion ('Do NOT use for crawling page body content') and names two alternative sibling tools, leaving no ambiguity about 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a clear 'Safe, read-only validation tool. No file modifications' statement, which reinforces the annotation without contradicting it. It doesn't add much beyond the annotations, but the explicit 'No file modifications' is useful 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?

The description is compact and front-loaded with the core purpose, followed by clearly labeled usage and behavioral sections. Every sentence earns its place, and the structure makes it easy for an agent to parse.

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 single-parameter read-only validation tool, the description covers purpose, usage boundaries, and safety. It doesn't describe the output format, but there is no output schema and the tool is simple enough that an agent can infer the validation result. The only minor gap is not describing what the return value looks like, but this is not critical for a validation 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 the single 'target' parameter. The description adds context about what the target is used for (inspecting structured data) but doesn't add new semantic detail beyond the schema. 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?

The description states a specific verb ('Extracts and validates') and a specific resource ('Schema.org JSON-LD structured data'), and enumerates the supported schema types. It clearly distinguishes this from sibling audit tools by naming the exact data format and validation focus.

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 states when to use the tool ('Use to inspect whether structured data is correctly embedded...') and when not to use it, naming the alternative tool ('seo_generate_code_fix') and the parameter to use. This is exactly the kind of routing guidance an agent needs.

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 read-only, idempotent, and non-destructive hints. The description adds valuable behavioral context beyond annotations: it issues HTTP GET requests, respects robots.txt and maxPages limits, and makes no disk modifications. This goes beyond the annotation hints, earning a 4.

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 structured with clear sections (purpose, usage guidelines, behavioral transparency). While longer than minimal, each section contributes essential information. The purpose is front-loaded, and the structure aids readability. It is not overly verbose for the tool's complexity, earning a 4.

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 gives an idea of output (scorecard and inventory report). It lacks output format details, but that is not critical given it is a crawl/audit tool. With annotations covering safety and schema covering parameters, the description is adequately complete for an agent to use 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?

All three parameters are fully described in the input schema (100% coverage), so the baseline is 3. The description does not add parameter-specific details beyond what the schema provides; it only indirectly references maxPages in the behavioral section. No extra value is added, so a 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 clearly states the tool's function: it crawls and batch-audits all pages from a sitemap, cross-checks robots.txt, audits HTTP security headers, and compiles a site-wide scorecard. It explicitly distinguishes itself from single-page tools by referencing seo_generate_full_audit, making the purpose unambiguous.

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 contains a dedicated USAGE GUIDELINES section that explicitly states when to use this tool (multi-page audits) and when not to (single-page or sitemap generation). It names the specific alternative tools (seo_generate_full_audit and seo_generate_sitemap_and_robots), leaving no decision 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 declare readOnlyHint, openWorldHint, idempotentHint, and destructiveHint=false, but the description adds concrete operational detail: it issues HTTP GET requests for URLs, reads local files for paths, and makes no disk modifications. This goes beyond annotation-only knowledge, though it stops short of describing response format or error behavior, which are minor for a safe diagnostic tool.

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 core purpose, followed by routing guidance and behavioral notes, all in clearly labeled sections. Every sentence provides actionable information without repetition or 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?

For a read-only audit tool with clear annotations and detailed parameter descriptions, the definition covers purpose, usage exclusions, and operational behavior. The only notable omission is any description of the audit output/return shape, which is not critical because there is no output schema and the tool's purpose strongly implies a report.

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?

The input schema has 100% coverage and already describes target as a live URL or local file path and projectPath as an optional root for locating sitemap.xml and robots.txt. The description adds behavioral context for target (HTTP GET vs file read) but does not materially expand parameter-level semantics beyond the schema, so 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?

The description opens with a specific verb and resource: 'Performs a Technical SEO audit on a page or URL' and enumerates concrete checks (canonical tags, robots meta tags, XML sitemap alignment, trailing slashes, mixed content, viewport, charset). This distinguishes it clearly from content, performance, and full-site sibling tools such as seo_audit_onpage and seo_audit_sitemap_multipage.

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 USAGE GUIDELINES section explicitly states what the tool is for (indexing, crawlability, canonicalization, technical header directives) and what it is not for, naming alternatives: seo_audit_onpage for copy/headings and seo_audit_sitemap_multipage/seo_generate_full_audit for full-site audits. This gives the agent unambiguous selection criteria.

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, idempotentHint=true, and destructiveHint=false. The description adds concrete behavioral details: it issues HTTP GET requests for live URLs and reads local files without modifying them. This extends the annotation information with specific network and file access behavior, which is valuable 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?

The description is well-structured with clear sections (main purpose, USAGE GUIDELINES, BEHAVIORAL TRANSPARENCY). It front-loads the core purpose and is not overly verbose. Minor redundancy exists (e.g., 'Read-only data extraction' appears both in the main text and the behavioral section), but overall it is efficient and scannable.

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 single-page extraction tool, the description is complete: it lists the exact metadata extracted, gives usage boundaries, and covers behavioral notes. There is no output schema, but the list of extracted items gives sufficient context. It does not describe the output format in detail, but that is not critical for 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?

Schema description coverage is 100% for both parameters. The description does not add any additional meaning beyond what the schema already provides for 'target' and 'pageType'. It restates the same information (e.g., live URL or local file path) without further nuance. 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?

The description clearly states the tool crawls a live URL or parses a local HTML/template file to extract a specific list of SEO metadata (Title, Meta Description, Headings, etc.). It uses a specific verb ('Crawls') and resource, and distinguishes itself from specialized audits by noting it is for extraction before running 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?

Explicit usage guidelines are provided: use for single-page metadata extraction, do not use for multi-page batch crawling (explicitly names seo_audit_sitemap_multipage), and do not use for framework discovery (names seo_discover_project). This gives clear when-to-use and when-not-to-use with alternatives.

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?

The description adds context beyond annotations: 'Safe, read-only local filesystem scan. Makes no network calls and modifies no files.' This specifies the scan scope (local filesystem) and network behavior, which annotations do not cover. Given that annotations already declare readOnlyHint, idempotentHint, and destructiveHint, the added detail is useful but not extensive; a 4 is appropriate.

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-organized with sections for usage and behavior, but it is slightly verbose—'Safe, read-only local filesystem scan. Makes no network calls and modifies no files.' could be condensed. The primary purpose is front-loaded in the first sentence, and the structure is logical, earning a 4.

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 tool with a single simple parameter and no output schema, the description covers the core functionality, usage, and behavior comprehensively. It lists the types of information discovered (frameworks, routing, sitemap/robots, page inventory), which is sufficient for an agent to invoke it correctly. No critical information 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?

The input schema already documents the single parameter (projectPath) with full 100% coverage, including default and example. The description does not add any parameter-specific meaning, so the baseline of 3 applies since the schema handles the burden.

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 a specific verb ('Discovers') and a concrete resource: website architecture, frameworks, routing, sitemap/robots, and page inventory. It distinguishes itself from sibling tools by specifying it operates on a local codebase, which is a clear differentiator.

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 usage guidance is provided: 'Use when starting an audit of a local codebase' and 'Do NOT use for remote websites or live URLs; use 'seo_crawl_and_extract' or 'seo_audit_sitemap_multipage' instead.' This names alternatives and conditions, leaving no ambiguity.

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?

Even though annotations already indicate non-destructive behavior, the description adds valuable precision: it returns a unified diff preview by default and only modifies disk contents when 'applyDirectly' is true. This clarifies the exact side-effect boundary beyond what annotations provide, and no contradiction exists.

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 structured into purpose, usage, and behavioral transparency sections, with every sentence earning its place. The core capability and framework list are front-loaded, and the safe-by-default behavior is stated in two concise 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?

For a tool with 8 parameters, one nested object, and no output schema, the description sufficiently explains what is generated, for which frameworks, when to invoke it, and what the return format is (unified diff preview). The workflow guidance to validate after applying makes it functionally complete.

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 8 parameters already carry detailed descriptions. The tool description enumerates the fix categories that map to these parameters, but it does not add per-parameter semantics beyond the schema. Baseline 3 is the appropriate baseline when the schema does the heavy lifting.

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 names a specific verb ('generates'), a specific resource ('code fixes') and enumerates exact fix categories (titles, meta descriptions, canonical URLs, JSON-LD, WebMCP discovery links) and target frameworks. It is clearly differentiated from its siblings: audit tools detect issues, this one fixes them, and seo_validate_code_fix validates 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?

The USAGE GUIDELINES explicitly state when to use the tool ('Use after audit tools detect specific...issues') and when not to use it ('Do NOT use for general code refactoring'). It also names a required follow-up sibling, seo_validate_code_fix, giving the agent a complete workflow.

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, idempotentHint, and destructiveHint. The description adds useful context beyond this by explicitly calling out 'Safe, read-only comprehensive synthesis' and 'Generates Markdown and JSON reports without modifying files.' It doesn't disclose whether live network requests occur, but given the strong annotation coverage this is not a serious gap.

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 logical sections (overview, USAGE GUIDELINES, BEHAVIORAL TRANSPARENCY) and front-loads the core function. Bullet points keep the alternatives scannable)Skip. Slight redundancy between 'read-only' and 'without modifying files' costs it a perfect score.

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 tool with no output schema, the description usefully lays out the key return artifacts (scores, grades, P0-P3 matrix, Markdown/JSON reports) and the explicit single-page scope. Combined with full schema coverage, this gives an agent enough to select and invoke the tool correctly, though more detail on input edge cases or authentication would be needed for a perfect score.

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%; the schema already fully documents 'target' as a live URL or local file path and 'projectPath' as optional framework/routing context. The description adds no further parameter-level meaning, so the baseline score 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 opens with a specific verb and resource: 'Executes the comprehensive 8-dimension audit suite' and enumerates all eight dimensions. It also lists concrete outputs (0-100 scores, letter grades, P0-P3 action matrix, Markdown report), making the tool's scope unmistakable and clearly distinct from single-dimension siblings.

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?

A dedicated USAGE GUIDELINES section explicitly defines when to use the tool as the 'primary single-page audit tool' and when not to: multi-page crawls point to 'seo_audit_sitemap_multipage', and single-dimension needs point to dedicated 'seo_audit_*' tools. This is concrete, actionable routing guidance.

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?

The description states 'Safe, read-only strategic synthesis' and 'without modifying any files,' which aligns with annotations (readOnlyHint true, destructiveHint false). It adds value beyond annotations by disclosing the output format as 'strategic Markdown plans,' which is not present in the structured data. 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 well-organized with clear sections (purpose, usage guidelines, behavioral transparency) and front-loads the main action in the opening sentence. It is concise yet thorough, with no filler; every sentence contributes essential information for correct tool selection and invocation.

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 strategic synthesis tool with multiple outputs, the description covers purpose, usage, and behavioral traits. It lists the components of the blueprint and provides routing guidance. While it doesn't detail the exact Markdown structure, the description is sufficient for an agent to decide when to use it and what to expect. The absence of an output schema is partially mitigated by mentioning Markdown output.

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 target and projectPath have descriptive text in the schema). The tool description does not add parameter-specific guidance, but the schema already documents both parameters adequately. Thus, the description adds no extra semantic value beyond the schema, earning the baseline score 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 the tool 'Synthesizes audit findings into a high-impact digital marketing growth blueprint' and enumerates specific components (search intent mapping across ToFu/MoFu/BoFu, CRO levers, AEO tactics, 30-60-90 roadmap). It also differentiates from siblings by naming alternatives like seo_generate_code_fix and seo_audit_technical, making its unique role unambiguous.

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 includes an explicit 'USAGE GUIDELINES' section with clear when-to-use scenarios ('Use when preparing a strategic marketing plan, client proposal, or business growth recommendations based on site audit data') and when-not-to-use exclusions with named alternatives ('Do NOT use to apply code fixes... use seo_generate_code_fix instead' and 'Do NOT use for quick technical diagnostic checks; use seo_audit_technical instead'). This provides complete routing guidance.

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, and non-destructive hints. The description adds critical behavioral context: it returns file contents as text output and does not write to disk unless copied by the user. This goes beyond the annotations and clarifies the side-effect-free nature.

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 (USAGE GUIDELINES, BEHAVIORAL TRANSPARENCY). The main purpose is front-loaded, and every sentence adds value. It's concise despite covering multiple aspects.

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 simplicity and full schema coverage, the description covers all necessary context: what it generates, when to use it, what it returns (text output, no disk write), and which sibling tools to use instead. No output schema exists, but the return format is explicitly stated.

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 each parameter (urls, targetUrl, disallowedPaths) already described. The description itself doesn't add parameter-level meaning, but it doesn't need to given the schema coverage. 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?

The description states a specific verb and resource ('generates sitemap.xml and robots.txt') and names the exact output format and crawler directives. It also explicitly distinguishes itself from sibling audit tools in the usage guidelines, so an agent can tell it apart without opening schemas.

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 when-to-use ('missing sitemap.xml or robots.txt, or needs clean, updated configuration files') and when-not-to-use conditions, naming the specific alternative tools for audits and crawls. This is unambiguous guidance.

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, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds a clear statement that it makes no modifications to codebase or remote sites, which reinforces the read-only nature and adds context beyond the annotations. It doesn't disclose rate limits or data source specifics, but for a read-only analysis tool this is adequate.

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 compact and front-loaded: the first sentence states the core purpose, and the USAGE GUIDELINES and BEHAVIORAL TRANSPARENCY sections are each one or two sentences with no filler. Every sentence earns its place.

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 single-parameter, read-only analysis tool with no output schema, the description covers the purpose, usage boundaries, and safety profile. It doesn't describe the return format, but with no output schema and a simple input, an agent has enough to invoke it correctly. Minor gap: it doesn't mention whether the target must be a local path vs. live URL, but the schema already covers that.

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 fully documents the single 'target' parameter. The description adds context about what the tool does with that target but doesn't add parameter-level detail beyond the schema. Baseline 3 is appropriate when the schema carries the full parameter documentation burden.

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 uses a specific verb ('Analyzes') and names the resource ('a website') and the four concrete outputs: market vertical, competitor archetypes, backlink/directory targets, and keyword topic clusters. This clearly distinguishes it from sibling audit tools like seo_audit_onpage or seo_generate_code_fix, which focus on different concerns.

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 USAGE GUIDELINES section explicitly states when to use the tool (expand organic reach, plan off-page directory submissions, identify competitor benchmarks) and explicitly names two sibling tools to avoid: seo_generate_code_fix for on-page code repairs and seo_test_web_mcp for protocol validation. This is exactly the kind of when/when-not guidance an agent needs.

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 and destructiveHint, and the description adds concrete details: it is a read-only diagnostic probe that makes HTTP GET/HEAD requests to standard discovery endpoints and modifies no files. This is useful context beyond the annotations, though it stops short of discussing response shapes or edge cases such as timeouts or redirects.

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 tightly organized with labeled sections, front-loads the core purpose, and contains no filler. The negative usage guidance earns its place because it prevents confusion with similarly named SEO sibling tools.

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 two-parameter tool, the description covers what it probes (specific endpoints), what it returns at a high level (implementation blueprints), and when it should or should not be used. No output schema exists, but the description gives an agent enough behavioral context to 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 both parameters are already documented thoroughly. The description's mention of '11 programming languages' and 'copy-paste implementation blueprints' reinforces the targetLanguage parameter, but it adds only marginal meaning beyond the schema's existing 'code blueprints' phrasing.

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 states a specific verb ('Tests'), a target resource ('live website or local endpoint'), and a precise objective ('Web MCP enablement'), then enumerates the exact checks performed. It also explicitly names sibling tools that it is not, so an agent can distinguish it from seo_audit_technical and seo_audit_onpage without opening their schemas.

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 a dedicated USAGE GUIDELINES section with a positive condition ('use to test if a web application exposes...') and an explicit negative condition with named alternatives ('Do NOT use for regular... use seo_audit_technical or seo_audit_onpage instead'). This leaves no ambiguity about when to invoke 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?

Beyond the readOnly/idempotent/destructive annotations, the description states that the tool reads the modified file, performs AST/regex checks, and makes no further modifications. This extra mechanistic detail confirms it is safe and explains how validation occurs without contradicting 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 one-sentence summary is front-loaded and every section adds useful context, but 'Safe, read-only file validation' and 'without making further modifications' are somewhat redundant with each other and the annotations. Still tight and scannable.

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 two-parameter validation tool with rich annotations, the description is nearly complete: it covers invocation timing, exclusions, alternatives, and what is checked. It falls just short of fully describing the output/return format, which matters here because there is no output schema to fill that gap.

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 filePath and the optional beforeScores map. The description reinforces the before/after scoring concept but adds no parameter-level meaning beyond the schema, so it meets 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?

Description states a specific verb ('validates') and resource ('modified source files'), enumerates the exact checks (syntax errors, duplicate meta/title tags, broken JSON-LD) and adds the score-delta behavior. It clearly distinguishes itself from sibling audit tools by framing validation as the follow-up to seo_generate_code_fix, not a standalone audit.

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 ('immediately after generating or applying a code fix via seo_generate_code_fix') and when not to ('do NOT use as a standalone audit on unedited files'), naming seo_audit_onpage or seo_generate_full_audit as alternatives. No ambiguity remains about placement in the workflow.

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