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

Adds value beyond annotations by stating it is static analysis ('No browser, no network'), confirming readOnly and idempotent behavior. Annotations already cover safety profile.

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 concise sentences: core function, usage context, and sibling comparisons. Every sentence provides unique value with 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?

Fully covers purpose, usage, and what the tool does not do. With output schema present, no need to explain return values. Sibling differentiation is excellently handled.

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 mentions 'static a11y + UX analysis' which gives context but doesn't add specific parameter details 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?

Clearly states verb 'analyze' and resource 'component's source' with specific frameworks. Differentiates from siblings audit_repo and audit_url by contrasting 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?

Explicitly says 'Best for pre-commit feedback on a snippet' and provides clear when-not instructions by naming alternatives audit_repo and audit_url.

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 readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds context that the tool runs multiple engines and returns fix suggestions, but does not disclose behavioral traits beyond what annotations provide. 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?

Two sentences with no waste. The leading '[a11y]' tag aids quick identification. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool complexity (4 params, output schema exists, annotations present), the description covers purpose, key parameters, and optional saving. It is sufficient for an agent to understand and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter descriptions. The description adds value by explaining baseline_name as saving for future diff and mode as audit depth levels, going 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?

Description clearly states it's a multi-engine accessibility audit on a URL, listing specific engines (axe-core, AccessLint, VertaaUX) and output type (normalized WCAG findings with fix suggestions). This distinguishes it from sibling tools like diff_a11y and run_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?

Description mentions saving findings for diff via baseline_name, providing a clear use case. However, it does not explicitly state when to use this tool vs alternatives like run_audit or analyze_component, missing explicit exclusions.

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 basic hints (readOnlyHint=false, etc.), but the description adds key behavioral details: supported artifact types (har, lighthouse), that playwright-trace is invalid, and that omitting url_hint causes local IDs that don't cross-reference with live 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?

Two well-structured sentences plus a list – no filler. First sentence states purpose and use cases, second specifies supported types, third gives exclusion. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, an output schema, and annotations, the description covers purpose, usage, parameter details, and behavior completely. It provides all necessary context for correct 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 coverage is 100%, but description adds meaning beyond schema: it clarifies artifact_type enum values (especially that playwright-trace returns error), and explains url_hint's role in cross-referencing findings with audit_url runs.

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 a captured browser artifact (not live URL), with specific use cases like CI debugging and bug reports. It distinguishes from sibling tools like audit_url by focusing on artifacts.

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: 'Use for CI-run debugging or customer bug reports without re-running the browser.' It also tells when not to use: 'playwright-trace returns INVALID_PARAMS, use audit_url'. This provides clear 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 indicate non-destructive behavior (readOnlyHint=false, destructiveHint=false). The description adds context by specifying it is a static scan and lists types of issues detected. While it does not detail side effects, the nature of a static scan is non-mutating, and annotations already cover safety.

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 (two sentences), front-loaded with the core purpose, and includes a sibling distinction. Every sentence adds value 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?

Given the existence of an output schema (as indicated by context signals) and the clear parameter documentation, the description is complete. It explains the tool's role, what it detects, and when to use an alternative, fully covering needed 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 descriptions cover all parameters (100% coverage), providing adequate documentation. The tool description does not add further meaning beyond the schema; it reiterates the tool's purpose but does not enhance parameter understanding.

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: 'Static UX + a11y scan of a local codebase tree' and lists specific detections (missing alt text, unlabeled elements). It also distinguishes from sibling 'audit_url' for live pages.

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 advises when not to use this tool ('For live pages use audit_url'), providing a clear alternative. It implies usage for local codebase scanning.

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 indicate it's not read-only (runs audit), not destructive, not idempotent. Description adds that offline mode is static-only, which is a behavioral constraint. It doesn't discuss rate limits or side effects beyond the audit computation. 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 one sentence with a short follow-up note. It is front-loaded with the purpose and uses concise language. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 7 parameters and output schema exists, the description covers the essential: what the tool does, output format (top 5 issues + scores), and a special mode caveat. It references a sibling for more details. It doesn't explain 'static-only' further, but with output schema present, it is fairly 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 baseline is 3. The description adds context about offline mode for localhost/file:// URLs, which adds meaning to the offline parameter. However, it doesn't elaborate on other parameters like timeout, wait, baseline_id, etc. The additional value beyond schema is marginal.

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 runs a full UX and accessibility audit on a live URL, returns the top 5 issues and scores, and distinguishes from get_findings for the full list. It also notes offline mode limitations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly tells when to use this tool (to get top issues) and when to use get_findings (for full list). It also mentions offline mode suitability for local HTML/Storybook. Could be slightly more explicit about when not to use, but it's clear enough.

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 discloses key behaviors beyond annotations: consumes audit quota, implemented via audit_url (not lightweight), and hints are advisory. Annotations only say readOnlyHint=false, which aligns with the consumption note, no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (two sentences) and front-loaded with the main purpose. The prefix '[session]' adds context, and every sentence contributes meaningful information. Could be slightly more structured, but overall 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?

Given 11 parameters and the presence of an output schema, the description adequately covers core behavior (screenshot+audit, quota consumption, advisory hints). It explicitly notes the implementation via audit_url, which provides context among siblings. Minor gap: no mention of return format, but 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?

Although schema coverage is 100% (baseline 3), the description adds value by clarifying that hints (viewport, fullPage, etc.) are advisory and not guaranteed to be honored. It also highlights mode='basic' as most cost-effective, aiding parameter selection.

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: 'Capture a hosted screenshot of a URL plus the full audit result.' This is a specific verb+resource+outcome, distinguishing it from lightweight screenshot tools by emphasizing it includes an 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?

The description offers a usage tip ('Use mode='basic' for cheapest') but lacks guidance on when to use this tool versus siblings like audit_url or run_audit. No explicit when-not-to-use or alternative comparisons are provided.

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 discloses that the tool runs N+1 fresh audits (not read-only), consumes quota, and returns side-by-side scores with differentiators. This adds context beyond the annotations (readOnlyHint=false, destructiveHint=false) without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core action, and each sentence provides essential information without redundancy. It is highly concise and structured effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description need not detail return format, but it still mentions scores and differentiators. It covers key behavioral aspects like parallelism, quota consumption, and use cases, making it complete 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 coverage is 100%, so the baseline is 3. The description adds value by mentioning 'parallel' execution, 'optional industry benchmarks', and quota consumption, but does not deeply elaborate on each parameter's usage. The added context 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 states a specific verb+resource: 'Audit your site vs N competitor URLs in parallel' and clearly distinguishes from sibling tool diff_audits, which compares existing audits. This makes 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 explicitly says 'Best for positioning, pitch decks, quarterly scans' and contrasts with diff_audits, stating when to use this tool (fresh audits) vs when to use the alternative (existing audits). It also notes quota consumption.

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 only indicate readOnlyHint=false and destructiveHint=false. The description adds behavioral details: returns markdown (not posting), patches ordered by severity, in-line suggestion blocks. 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?

Three concise sentences: first defines purpose, second and third compare to siblings. No wasted content; every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Description covers purpose, output format, and sibling differentiation. Given output schema exists and 2 required parameters, it provides sufficient context. Could mention prerequisites (e.g., PR context) but not necessary.

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 fully documents parameters. The description adds minor guidance about patches being ordered by severity, but does not compensate beyond baseline for high 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?

Description clearly states the tool generates a per-file GitHub PR comment with in-line suggestion blocks for a11y patches, ordered by severity, returning markdown. It also explicitly differentiates from siblings 'format_pr_comment' and 'generate_pr'.

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?

Description provides explicit comparisons to two sibling tools ('vs format_pr_comment' and 'vs generate_pr'), guiding when to use this tool instead. It does not include explicit 'when not to use' beyond those comparisons, but the context is clear.

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: counts against monthly quota, returns id + next_run_at, and explains alert trigger mechanism. 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?

Two sentences, front-loaded with purpose and use cases, no redundant information. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, use cases, alert configuration, and quota. Mentions return value. Lacks error handling or prerequisites, but adequate for a create tool with good schema and 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%, so baseline is 3. Description adds value by grouping alert parameters and explaining their combined effect, going beyond individual schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Create a recurring audit on a cron schedule' and gives specific use cases like 'daily a11y regression checks, weekly competitor diffs, post-deploy smoke audits', distinguishing it from one-time audit tools like run_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?

Description provides strong usage context (e.g., 'Best for daily a11y regression checks') and mentions quota impact, but does not explicitly contrast with siblings like run_audit or update_schedule.

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 (readOnlyHint=false, destructiveHint=false) are present. The description adds valuable behavioral context: HMAC-SHA256 signing, accepted event types, SSRF protection, and what is returned (id + active status). 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?

Three sentences efficiently convey purpose, mechanism, constraints, and usage hint. Front-loaded with main action, no wasted words.

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 with an output schema, the description covers all necessary aspects: purpose, how it works, constraints, return values, and preventative measure against duplicates. It is fully 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 coverage is 100%, and the description reinforces the parameter meanings with extra context (e.g., URL must be publicly reachable, secret used for signing). 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 verb 'register' and the resource 'HTTPS endpoint to receive audit event notifications'. It distinguishes from siblings by suggesting to use list_webhooks first to avoid duplicates, and implicitly distinguishes from delete_webhook.

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 guidance is given: 'Use list_webhooks first to avoid duplicates.' This tells the agent when to use creation versus checking existing webhooks. Also notes URL constraints and SSRF blocking, which inform usage conditions.

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 destructiveHint=true; description adds that deletion is permanent and cancels future runs, which enhances transparency 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?

Extremely concise single sentence with critical info front-loaded, no unnecessary words.

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 low complexity (1 param, destructive action, output schema exists), the description fully covers behavior, alternatives, and parameter sourcing. 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 has 100% coverage for the single parameter; description adds value by specifying how to obtain the ID (from list_schedules), which aids correct invocation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'permanently delete an audit schedule by ID' with explicit destructive connotation. Distinguishes from sibling tools like update_schedule and list_schedules.

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 advises to use update_schedule with enabled=false as a safer alternative, and directs to list_schedules for ID lookup, providing strong usage 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 signal destructiveHint=true. Description adds context: 'DESTRUCTIVE', 'permanently delete', 'No soft-delete', and 'future events stop delivering', which exceeds annotation information. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. Important terms like 'DESTRUCTIVE' are front-loaded. Each sentence adds essential information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only one parameter and an output schema present, the description completely covers the tool's purpose, usage, and effect. No additional context needed.

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 the single parameter with description 'Webhook ID to delete (from list_webhooks)'. The overall description reinforces the parameter's purpose by mentioning list_webhooks, adding value 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?

Explicitly states 'permanently delete a webhook by ID; future events stop delivering. No soft-delete.' Clearly identifies the action, resource, and effect, distinguishing it from sibling list_webhooks.

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?

Directs the agent to 'Look up ID via list_webhooks,' providing a clear prerequisite and when to use this tool. The destructive nature implies not to use for temporary disabling.

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?

Describes return categories (regressions, fixes, unchanged, net-change summary) and prerequisite that baseline must be saved via audit_a11y, going beyond annotations that already mark it read-only and idempotent.

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 sentences efficiently convey purpose, alternatives, and usage condition without fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 params, 2 required, output schema present, annotations present), the description covers when to use, what it does, prerequisites, and return types completely.

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, but the description adds critical context that the baseline parameter must be a named baseline saved via audit_a11y, which enhances understanding 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?

Description clearly states 'SECONDARY a11y diff using NAMED baselines' and lists return categories, distinguishing from sibling diff_audits with explicit preference and scope difference.

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 compares with diff_audits ('prefer that') and states condition for using this tool: 'only when you already have a named a11y baseline.'

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 and idempotentHint=true, making the tool's safety clear. The description adds value by detailing the specific data returned (HTML, screenshot, WCAG criteria, etc.) beyond what annotations convey.

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 a single, front-loaded sentence that immediately conveys the tool's purpose and outputs. No redundant words, and the usage hint is concise. Every part 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?

The description covers the tool's inputs, outputs, and usage context (after audit_url). An output schema exists, so detailed return format documentation is not needed. Given the tool's complexity, the description is fully adequate.

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, meaning each parameter already has a thorough description (e.g., 'Finding ID from get_findings (format: rule:hash)'). The description adds minimal additional meaning, so a 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 clearly states the action ('deep-dive'), the resource ('a specific finding by ID'), and the output (element HTML, screenshot URL, WCAG criteria, etc.). It also distinguishes from sibling tools like get_findings by indicating this is a deeper dive on a specific finding.

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 advises 'Use after audit_url to expand on a finding from get_findings', providing clear context on when to use this tool. It could improve by mentioning when not to use it, but the guidance is sufficient.

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=true. The description adds 'No network call' as extra behavioral context beyond annotations, confirming it is a client-side operation. 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?

Two sentences pack significant information without excess. First sentence lists outputs concisely; second sentence provides sibling comparison. Efficient but slightly dense.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of nested object input and presence of output schema, the description sufficiently explains the tool's purpose, scope, and differentiation. Missing details like output format are covered by 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?

Input schema has 100% coverage (both parameters described in detail with field descriptions). The description does not add new parameter-level information beyond what the schema provides, so 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 formats an inline audit issue object into developer-friendly guidance, listing specific outputs (WCAG explanation, user impact, code-level fix, reference links). It also distinguishes from the sibling `explain_finding` by noting this tool takes the issue literal directly rather than fetching by ID.

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 contrasts with `explain_finding`, stating that `explain_issue` takes an inline issue object and makes 'No network call'. This provides clear guidance on when to use this tool versus the alternative.

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 context beyond annotations: reveals legacy nature, lack of framework detection, and output contents (patch, confidence, explanation). Annotations already indicate it's not read-only and not destructive.

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?

Extremely concise: two sentences, front-loaded with key facts (legacy, output, comparison). Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 4 parameters, output schema, and sibling comparisons, the description covers purpose, usage guidance, and key distinctions without redundancy. 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?

Input schema has 100% coverage with descriptions for all 4 parameters. The description implies the role of job_id/issue_id and file_path/file_content but does not add new semantics 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?

Clearly states it's a LEGACY issue-based fix generator that returns a search/replace patch with confidence and explanation. Distinct from suggest_fix, which is framework-aware and preferred.

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 advises to use generate_patch only for legacy job_id/issue_id consumers, and compares to suggest_fix as the preferred alternative with framework-awareness.

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?

Despite annotations being minimal (readOnlyHint=false, destructiveHint=false, idempotentHint=false), the description adds rich behavioral context: atomic all-or-nothing commit, refusal of conflicts and invalid AST, draft-only creation, no auto-merge, and token requirement. 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?

Description is dense but well-structured, starting with main purpose and then detailing constraints and inputs. Some redundancy could be trimmed, but it's efficient overall.

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, guidelines, behavior, parameter context adequately. Given presence of output schema, description focuses on inputs and behavior. Minor omission: error handling beyond CONFLICT and AST_INVALID, but not critical.

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 description adds supplementary context: patches come from suggest_fix, local_only as fallback without token. This adds value beyond schema definitions.

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 opens a draft GitHub PR with a11y patches applied atomically via Git Trees, distinguishing it from siblings like suggest_fix and generate_patch. It specifies it always creates draft PRs and never auto-merges.

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 (with patches from suggest_fix, preferred) and alternatives (generate_patch is legacy). Provides conditions: requires GITHUB_TOKEN; otherwise set local_only=true. Also mentions it refuses overlapping patches and unparseable files.

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 read-only, non-destructive, idempotent behavior. Description adds return format details (status, progress, scores, issues) not in 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?

Three concise sentences, front-loaded with purpose, no wasted words.

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, description covers key return fields, usage context, and ID namespace. Complete for effective use.

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 job_id with description of field name variations. Description adds value by stating same ID namespace across all audit tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states the tool fetches status and results of an audit job, distinguishing it from sibling tools that initiate audits.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends polling after specific audit initiation tools when wait=false, and notes the shared ID namespace.

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 safe, read-only, idempotent behavior. Description adds valuable context about quota implications and the structure of results (semver, alias, release notes), exceeding 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?

Two concise sentences: first defines action and scope, second provides use cases. No wasted words, information 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?

Description covers purpose, usage, quota context, and result structure. Annotations and output schema complement it well, making the definition complete for this simple listing 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?

No parameters in schema, so description doesn't need param details. It implicitly confirms no input required, meeting baseline for zero-parameter tool.

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 lists audit engine versions, specifying semver releases, 'latest' alias, and release notes. It distinguishes the tool from siblings by focusing on engine version listing, not auditing or analysis.

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 mentions two use cases: pinning audits and discovering newer analyzers. Provides clear context for when to use, though no explicit exclusions or 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 and destructiveHint=false. Description adds pagination/filtering context but no additional behavioral traits 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?

Two sentences, but the first includes a redundant tag '[findings]' that could be removed. Otherwise concise and 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?

With output schema existing and annotations covering safety, the description is complete for a filtering tool, though it doesn't detail return structure.

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%, and description mentions filtering and pagination parameters but adds no syntax or format details 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?

Description clearly states verb (Get) and resource (findings), specifies pagination and filtering options, and guides usage after other audit tools, distinguishing it from 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?

Explicitly says 'Use after audit_url/audit_repo/audit_artifact for detailed findings,' providing sequential context, though no exclusion or alternative tools are mentioned.

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 and idempotentHint=true, so safety is clear. The description adds value by listing the exact data returned (tier, audits remaining, reset timestamp, feature flags) and the rationale for pre-batch usage, which goes 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?

Two sentences, no redundancy. First sentence front-loads the purpose and return fields; second sentence provides crucial usage guidance. Every word 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 zero-parameter, read-only tool with a full output schema, the description covers all essential aspects: return fields, usage scenario, and purpose. 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?

No parameters exist, so the description has no burden. The schema coverage is 100%, and the description adds context about what values are returned, which is appropriate. Baseline 4 for zero-parameter tools.

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 specifies the verb ('Get') and resource ('the authenticated account's tier, audits remaining, reset timestamp, and feature flags'). It differentiates itself from siblings by focusing on quota information, with no other sibling serving a similar purpose.

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 advises 'Call before batch audits to avoid mid-run quota errors,' giving a concrete use case and timing recommendation. No exclusions or alternatives needed given the tool's unique purpose.

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 the tool as read-only, idempotent, and non-destructive. The description aligns by stating 'Read'. It adds transparency by listing the fields returned. No contradiction. However, it does not disclose any additional behavioral traits 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?

The description is extremely concise - two sentences that convey purpose, return fields, and ID lookup method. 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 tool with output schema, the description covers everything needed: purpose, ID source, and return fields. It is fully 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?

The schema already describes the 'id' parameter fully. The description adds useful context on how to find the ID (via list_schedules), which aids the agent. Since schema coverage is 100%, baseline is 3, and the added context raises it to 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 uses a specific verb 'Read' and specifies the resource 'audit schedule by ID'. It enumerates the fields returned, and explicitly references sibling tool 'list_schedules' for ID lookup, distinguishing its purpose.

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 provides clear context for when to use (after ID obtained from list_schedules) but does not state exclusions or alternative tools explicitly.

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=true. The description adds value by listing returned fields and the usage hint, but does not contradict annotations. No additional behavioral traits beyond annotations are missing.

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 a single sentence that front-loads the tool category and action, then lists fields and usage hint. No wasted words.

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 no parameters and an existing output schema, the description adequately explains what the tool does, what it returns, and how it should be used in a workflow. 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?

The input schema has no parameters, so schema description coverage is 100%. The description does not need to add parameter info; baseline 4 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 lists all audit schedules and mentions specific fields returned (ID, target URL, cron, etc.). It distinguishes from siblings by explicitly saying to use it before update_schedule or delete_schedule for ID lookup.

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 usage guidance: 'Use before update_schedule or delete_schedule to look up the ID.' It does not mention when not to use or alternatives like get_schedule, but the context is clear.

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=true, so the safety profile is clear. The description adds context about the specific fields returned, which is helpful 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?

Short and front-loaded: starts with a tag, then lists output fields concisely, then gives usage guidance. Every sentence adds value, no wasted words.

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 zero parameters, clear annotations, and an output schema, the description is complete: it tells what the tool returns and when to use it relative to siblings.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters with 100% coverage, so baseline is 4. No parameter info needed; description adds no param info, which 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 it lists webhooks on the account, specifying the output fields (ID, URL, subscribed event types, active status, last-delivery timestamp). This distinguishes it from sibling tools like create_webhook and delete_webhook.

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 'Use before create_webhook (avoid duplicates) or delete_webhook (look up ID).' This provides clear when-to-use and 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 does not add behavioral information beyond what annotations provide. Annotations indicate readOnlyHint=false and destructiveHint=false, but the description merely states it is an audit tool. It does not clarify side effects or any behavioral traits, so it fails to add value beyond the structured fields.

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 extremely concise, consisting of a single sentence that immediately conveys the category, deprecation status, and recommended alternative. No wasted words; front-loaded with key 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?

The description is complete for a deprecated tool: it tells the agent what it does and what to use instead. However, it could mention that the tool still functions for legacy clients, but the context of deprecation is sufficient. Output schema exists but is not referenced.

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?

Input schema has 100% description coverage for all 7 parameters. The description does not elaborate on any parameter meanings, but the baseline is 3 since schema already fully documents them. No additional semantic value added.

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 explicitly labels the tool as an audit tool ('[audit]') and clearly states it is deprecated, directing the agent to use 'audit_url' instead. This leaves no ambiguity about the tool's function and its intended replacement.

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: only use this tool for legacy clients, and otherwise use 'audit_url'. This is a clear directive on when and when not to use the tool, with a named alternative.

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 provide basic safety hints, and the description adds key behavioral context: it consumes LLM credits and operates via an external adapter. No contradiction, but could further disclose side effects like persistence.

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 extremely concise: two sentences plus a contrast line, front-loaded with the core function. Every sentence adds value with 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 the existence of an output schema, the description sufficiently covers purpose and usage boundaries. It could mention prerequisites like URL accessibility but remains largely 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?

Input schema covers all three parameters with descriptions (100% coverage). The tool description adds no additional parameter detail beyond indicating the nature of the audit.

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 performs an LLM-based UX audit on a URL, listing specific qualitative aspects like hero clarity and messaging, and distinguishes itself from the rule-based sibling audit_url.

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 contrasts with audit_url (rule-based WCAG/a11y) and notes LLM credit consumption, providing clear guidance on when to use this tool and its resource implications.

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 behavioral traits: runs in a sandboxed browser, performs before/after axe-core checks, returns score delta and rule pass. Annotations indicate non-destructive and non-read-only; description adds meaningful process details without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (3-4 sentences), front-loaded with the key action, and every sentence adds value. No superfluous wording.

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 main use case, parameter sourcing, and distinguishes from an alternative. With an output schema present, the description does not need to detail return format extensively. However, it could mention error handling or prerequisites for completeness.

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 description significantly augments the input schema by providing practical guidance for obtaining the selector (from get_findings, explain_finding, or finding.node.target), explains rule_id sourcing, and clarifies constraints like URL must be live. All 6 parameters are covered.

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 as pre-deploy patch verification, specifying it tests a proposed patch against a live URL in a sandboxed browser. It distinguishes from verify_fixes (post-deploy comparison) and uses 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 states when to use (pre-deploy, before commit) and contrasts with the alternative verify_fixes (post-deploy). Provides clear context for 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, destructiveHint=false, idempotentHint=true, covering safety. The description adds that output includes patch, confidence, framework_confidence, and needs_human_review, plus framework detection via nearest package.json, providing behavioral detail 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?

Two sentences (though second is fragmented) are reasonably concise. Purpose is front-loaded. Some redundancy (e.g., listing frameworks) but overall 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?

Given an output schema exists, the description covers all necessary aspects: input parameters, modes, output summary, framework detection, and integration with sibling tools. No gaps for the complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description adds value by explaining single vs batch mode (finding_id vs finding_ids) and mentioning optional file_content/file_path for better accuracy, augmenting the schema's concise descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as a 'PRIMARY framework-aware fix generator' that produces search/replace patches for various frameworks. It explicitly distinguishes from sibling 'generate_patch' as the legacy variant, leaving no ambiguity.

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 clear usage instructions: pass finding_id + audit_id, single or batch mode, and suggests piping to generate_pr or run_verification_suite. Does not explicitly mention when not to use, but context is sufficient.

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 this is a mutation (readOnlyHint=false) and not destructive (destructiveHint=false). The description adds that it is a partial update (affects only provided fields) and provides examples like pausing via enabled=false, which is 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 extremely concise: two sentences. The first sentence states the purpose, the second provides prerequisite and common examples. No unnecessary words.

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 11 parameters, mutation nature, and existence of an output schema, the description covers prerequisites, common use cases, and partial update semantics. It does not detail return values (handled by output schema) or side effects, but is sufficient for typical usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by linking parameters to common tasks (e.g., 'pause via enabled=false, change cadence via cron_expression, add score-drop alerts'), providing meaningful context beyond individual parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Partial update of an audit schedule', specifying the verb (update) and resource (audit schedule). It distinguishes from sibling tools like create_schedule, delete_schedule, get_schedule, and list_schedules by being the sole update operation.

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 context for when to use this tool, advising to 'Use list_schedules to look up ID' and giving common use cases (pause, change cadence, add alerts). It does not explicitly state when not to use, but the examples cover typical modifications.

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