plan_audit

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

With no annotations provided, the description carries full burden and does well by describing the multi-step process (discover sitemaps, identify patterns, estimate counts, generate strategy). It mentions what the tool returns (sitemap validation, route classification, sampling strategy, issues/warnings) and its non-destructive nature (analysis only). However, it doesn't specify performance characteristics like rate limits or timeout 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?

The description is well-structured with clear sections (purpose, process steps, returns, usage guidance) and front-loads the most important information ('RECOMMENDED FIRST STEP'). While comprehensive, it could be slightly more concise by combining some of the bullet points about returns into a single sentence.

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 3 parameters, 100% schema coverage, and no output schema, the description provides excellent context about what the tool does, when to use it, and what it returns. It explains the multi-step analysis process and connects to sibling tools. The main gap is the lack of output schema, but the description compensates by listing return categories.

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 all three parameters adequately. The description doesn't add any additional parameter semantics beyond what's in the schema - it focuses on the tool's purpose and outputs rather than explaining parameter usage. This meets the baseline expectation when schema coverage is complete.

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 with specific verbs ('analyze sitemaps', 'create sampling strategy') and resources ('large sites', 'job boards'). It explicitly distinguishes from siblings by recommending use 'BEFORE crawl_site or sample_pages' and mentions alternative tools like Lighthouse analysis, showing clear 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 provides explicit guidance on when to use this tool ('RECOMMENDED FIRST STEP', 'essential for job boards and large sites with 100k+ pages', 'BEFORE crawl_site or sample_pages') and when not to use it (for small sites or direct analysis). It names specific alternative tools (crawl_site, sample_pages, Lighthouse) for different scenarios.

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