webability

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

Annotations already cover the safety profile (readOnly=false, destructive=false, idempotent=false, openWorld=true). The description adds meaningful context beyond them: the 30-day full-widget window, the included first scan, the return fields (site id and plan tier), and the account requirement.

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

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

Front-loads the core action, then workflow guidance, then the prerequisite. Every sentence contributes, though the parenthetical about self-signup is slightly tangential.

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?

No output schema, but the description names the return values (site id and plan tier) and the follow-up tools, plus the account prerequisite. It covers what an agent needs to invoke and chain this correctly, missing only edge cases like duplicate-domain handling.

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 carries the parameter documentation burden. The description adds no parameter-specific syntax or constraints beyond what the schema already states, which is the baseline 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?

States a specific verb and resource: "Add a website to the signed-in WebAbility account." It clearly distinguishes itself from siblings like list_sites and get_install_snippet, so an agent can tell what it does without opening the schema.

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

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

Provides explicit next-step routing ("put the get_install_snippet tag on the site, and use create_upgrade_link to get a payment link for the WebAbility Pro plan") and a prerequisite (needs a free account). It names related tools but does not state when-not to use this tool, so it stops short of full when/when-not coverage.

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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds substantial context beyond them: error semantics (an unmatched selector or HTTP error is an error, never 'no violations'), the default per-rule node cap of 5 with nodesTotal/truncated reporting, and the hosted-server refusal of localhost/private addresses with concrete workarounds.

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

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

Purpose is front-loaded in the first sentence, followed by rules, output, error semantics, caps, and a clearly delineated NOTE. It is dense and long, but nearly every clause carries operational information; only minor tightening is possible.

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 7-parameter, no-output-schema tool, the description covers return shape ('violations'), error conditions, truncation behavior, and the connectivity constraint that would otherwise cause silent failures. An agent has everything needed 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 coverage is 100%, so the baseline is 3. The description goes beyond the schema by clarifying selector semantics ('ARIA references outside it still resolve') and reiterating the nodeLimit default/max and tunnel_secret requirement, adding real invocation context.

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

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

States a specific verb (Validate) and resource (ARIA attribute + accessible name/role/value usage), and scopes it to an HTML snippet or a live page. It names the exact axe-core rule categories (cat.aria, cat.name-role-value), which distinguishes it from siblings like check_color_contrast and scan_page.

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

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

Explains the html-vs-url choice and the selector narrowing case, and even routes the local-dev-server scenario to either running the MCP locally or using a tunnel. It does not explicitly contrast itself against scan_html/scan_page, so the differentiation is implied rather than stated.

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

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

Annotations already cover read-only/idempotent safety, yet the description adds substantial behavioral context: gradient/image backgrounds are reported as errors rather than guessed, brand palette extraction behavior, and the critical hosted-server limitation (localhost/private addresses refused) with two concrete workarounds. This is exactly the kind of environment-specific constraint an agent needs.

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

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

Front-loaded with the core purpose and thresholds, then modes, then the hosted-server caveat. It is dense and long, but nearly every clause carries actionable information; the localhost/tunnel note could arguably be tightened but is not padding.

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 an 11-parameter tool with no output schema, the description covers return semantics (ratio, pass/fail, AAA verdict, brand-aligned suggestions), failure modes (gradient/image = error), and the environment constraint. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: the url/selector interaction (reads element colors, extracts palette on failure), the precedence of explicit colors, and the tunnel_secret requirement when url is a tunnel URL. It clarifies cross-parameter behavior the schema documents only per-field.

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

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

States a specific verb+resource ('Check text contrast against the WCAG AA threshold') with exact thresholds (4.5:1, 3:1 large text), clearly distinguishing it from siblings like check_aria or visual_audit. An agent immediately knows what the tool computes and returns.

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 lays out the two invocation modes (foreground/background pair vs url+selector), the precedence rule ('explicit colors win over the page'), and the degenerate case ('No url and no brandColors = ratio + pass/fail only'). It also names the alternative workflows for local dev servers (run MCP locally or use a tunnel), leaving nothing 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 declare readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false; the description adds genuinely new context beyond these — that the agent never handles card details, that plan activation happens automatically after payment, and that the site must already exist on the account. It does not clarify what happens if the link is requested twice, which the non-idempotent hint implies matters.

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

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

Five short sentences, front-loaded with the outcome (a checkout link) and then the operational essentials: who receives it, what happens after payment, the security boundary, and the prerequisite. No filler.

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

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

With no output schema, the description still covers the return artifact (a link to hand off), the post-call lifecycle (payment triggers activation), and the prerequisite chain. Nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100%, so domain, billing_interval, context, and llm_model are already documented at the schema level. The description only reinforces that the domain must correspond to a site added via add_site, adding marginal value — the correct 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?

States a specific verb and resource: returns a Stripe Checkout link that places one site on the WebAbility Pro plan. It is clearly distinguishable from siblings like add_site, list_sites, and the scan/audit 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 says who the link goes to (the human who pays), the prerequisite (site must be on the account, add_site first), the account requirement, and the follow-up verification via list_sites. An agent knows exactly when and why to call it.

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 safe read profile, but the description adds substantial non-obvious behavior: the hosted server refuses localhost/private addresses, requires `tunnel_secret` for tunnel URLs, and returns an evidence list plus the value to feed into `generate_ai_fix`.

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

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

Front-loaded with the core purpose before the network caveats, and each sentence carries information. It is dense and long, with the local-dev-server note consuming significant space, but nothing is pure filler.

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

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

With no output schema, the description fully carries the return-value burden by naming both output fields and the evidence list. Combined with the network/tunnel guidance, an agent has everything needed 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 coverage is 100%, so parameters are already documented, but the description adds real meaning by explaining how `tunnel_secret` is obtained and when it is required, and by tying `framework` output to the `generate_ai_fix` parameter.

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

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

States a specific verb and resource ('Detect a page's stack') and enumerates the exact output fields (`framework`, `cssToolkit`) with example values. It also distinguishes itself from the sibling `scan_page`, noting they return the same two fields from the same detection.

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 operating context: it explains that `scan_page` reports the same fields (implying when this narrower tool suffices), and gives explicit remediation paths for local dev servers. It lacks an explicit 'use this instead of X when you only need Y' statement, so it falls short of a 5.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description adds substantive traits beyond them: matching is done by issue id (rule + element), a changed class/id can make a fixed element read as both fixed AND new, and the hosted server refuses localhost and requires a tunnel secret. These are non-obvious behaviors an agent must know to interpret results correctly.

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

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

Front-loaded with the return shape, then the semantic caveat, then the usage loop, then the host constraint — a logical order where each block earns its place. It is dense and long, and some parameter commentary (e.g. tunnel_secret) partially duplicates the schema, but nothing is wasted or misleading.

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?

Although there is no output schema and 14 parameters, the description enumerates the returned keys, explains the four baseline/current parameters, and covers the deployment constraints. An agent has everything needed to call it and interpret the result 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, but the description adds a conceptual model the schema lacks: baseline is a history id or a live URL, current is a live URL or another history id, and the viewport should match the baseline. This clarifies the four-way relationship among url/currentId/baselineId/baselineUrl beyond the individual field docs.

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

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

States a specific verb and resource (compare two scans of the same page) and enumerates the exact output shape (fixed[], new[], remaining[]). It explicitly positions itself against a sibling — 'Page-level complement to verify_fix (one element)' — so an agent can distinguish the two without reading either schema.

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

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

Gives an explicit when-to-use loop (scan_page → edit → diff_scan → confirm new[] is empty), names the alternative (verify_fix), and describes the baseline/current source combinations. It also states a hard usage constraint (localhost/private addresses refused on this hosted server) with two concrete workarounds.

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 cover safety (readOnly, idempotent, non-destructive); the description adds substantial behavior: deterministic sequential rendering, one consolidated deduplicated report, the full set of per-page outcomes (scanned/nav_failed/scan_failed/... and blocked bot-challenge), and the guarantee a page is never silently dropped. It also discloses the hosted-server constraint that localhost/private IPs are refused, which is exactly the kind of behavioral context annotations cannot 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?

Front-loaded with the core behavior and outcome contract; each sentence carries information. The final local-host/tunnel sentence is long and slightly digressive, but it prevents failed calls, so it 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 12-param tool with no output schema, the description covers the return contract (one report, pages[] outcomes, deduped issues with fix payloads), the hosted-vs-local constraint, and the autoNavigate fallback. An agent has everything needed 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 coverage is 100%, so baseline is 3; the description adds meaning beyond the schema for autoNavigate ("walks ... sequentially", "omit ... to scan only startUrl") and tunnel_secret (required when url is a tunnel URL, ignored otherwise). This clarifies interaction between parameters that the schema documents only individually.

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

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

States a specific verb+resource ("Scan a multi-page user journey") and immediately differentiates itself from the sibling scan_page ("Without autoNavigate it scans only startUrl, exactly like scan_page"). An agent can distinguish its scope without opening the schema.

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

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

Explicitly states when to prefer it ("Better than per-page scans for journeys (login → checkout etc)"), the degenerate case that equals scan_page, and names two concrete alternatives for local-dev scanning (run MCP locally vs. tunnel). When/when-not/alternatives are all covered.

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 annotations, it discloses a hard reachability constraint (localhost/private addresses refused on the hosted server), the reason (cloud-hosted, cannot reach your machine), and two concrete workarounds including the secret requirement. This is exactly the kind of runtime behavior an agent cannot infer from annotations alone.

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

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

Front-loads the core capability with zero waste, then adds operational caveats in a clearly separated NOTE. Somewhat long, but every sentence (contrast-vs-ARIA branching, localhost refusal, tunnel secret) carries information the agent needs.

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

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

An 8-param tool with no output schema, yet the description covers output cardinality, auto-extraction behavior, and the hosted-server constraint. The remaining gaps (e.g., what happens on framework mismatch, latency/LLM variability) are minor.

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

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

Schema description coverage is already 100%, so baseline is 3. The description adds genuine meaning: brandColors auto-extracted from live URL when omitted, and tunnel_secret required for tunnel URLs. It exceeds the schema on those two params, though it does not elaborate on llm_model or context.

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

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

Specific verb ('generate') plus resource ('framework-aware fix alternatives for a specific accessibility issue'), with output shape made concrete (3 contrast alternatives, 1-2 label/ARIA alternatives, ready-to-paste code). This clearly distinguishes it from siblings like verify_fix or detect_framework.

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

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

Gives clear context for when each branch applies (contrast vs label/ARIA issues) and detailed guidance for the local-dev-server case, but does not name sibling alternatives (e.g., detect_framework first, verify_fix to validate) inside the description itself. Strong context, no 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 declare readOnly/idempotent/non-destructive/openWorld, yet the description adds material behavior they don't cover: download URLs are 'short-lived', ownership gates access, polling cadence, and the tool is free with an account. These are real operational traits an agent needs, not restatement of the hints.

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?

A single dense paragraph that front-loads the core purpose, then return values, then polling cadence and access constraints. No filler sentences; every clause carries actionable 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?

With no output schema, the description fully carries the return-value burden: status, per-step progress, severity summary, and JSON/Excel download URLs. Combined with auth, cost, and polling notes, an agent has everything needed to call and interpret 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% and the id field already documents 'The audit id returned by start_audit', which the description merely echoes. The description adds no format, range, or validation detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource ('Check an audit started with start_audit') and enumerates exactly what is returned, including the per-step pipeline (scan → viewports → screenshots → agent → excel → publish). It explicitly ties itself to the sibling start_audit, so an agent can distinguish it from scan_page or visual_audit without opening a schema.

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

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

Gives concrete operational guidance: 'Poll every ~15s while status is pending/running', names start_audit as the prerequisite producer of the id, and states the access restriction ('Only the account that started an audit can read it'). This is when-to-use plus when-not (you can't read others' audits) in one paragraph.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior. The description adds real context beyond that: no account is needed, the widget resolves the site by domain, and the same tag works across sites, which pre-empts a likely agent question about per-site variation.

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

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

Four short sentences, front-loaded with what the tool returns, then where to place it, then the domain-resolution detail. No filler or repetition.

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

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

For a simple zero-required-parameter getter with no output schema, the description fully covers the return value (a one-line script tag), placement, and the add_site dependency. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and both parameters (context, llm_model) are analytics-only plumbing fully documented in the schema. The description correctly omits them, so this is baseline rather than a gap.

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

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

States a specific verb and resource - returns the one-line script tag that installs the WebAbility widget - and ties it to a sibling (add_site) so the agent knows the prerequisite. It is clearly distinguishable from the scan/audit tools in the sibling list.

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

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

Gives concrete placement guidance (<head> or before </body>) and names the dependency on add_site. It does not state when the tool should NOT be called or offer an alternative, so it falls short of explicit exclusion 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, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral value beyond that: rule counts per engine, the three fixability tiers with their meaning, the presence of a fix op template, and the returned fields — enough for an agent to know what it gets back before calling.

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, both front-loaded: the first names the resource, both engines and the counts, the second explains the payload. No filler, and the payoff ('pick the rules worth auto-fixing before scanning') lands 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?

With no output schema, the description compensates by enumerating the returned fields (ruleId, engine, description, help, helpUrl, tags/wcag, fixability, fix), and all six parameters are optional and fully documented in the schema. Nothing an agent needs to select or invoke this tool is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description goes further by explaining what fixability values mean (mechanical | contextual | visual) and why one would filter on them, and by tying rule metadata to the filter. The 'context' and 'llm_model' analytics params are explained only in the schema, keeping it out of 5 territory.

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

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

States a specific verb and resource ('List accessibility rules from both engines') plus the exact scope (axe-core 104 rules, WebAbility 90+) and the optional-filter behavior. No sibling tool lists rules — the others scan, check, or fix — so the agent can tell this is the catalog lookup rather than an execution tool.

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

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

Gives a clear use context: filter by fixability 'so you can pick the rules worth auto-fixing before scanning,' which positions it as a pre-scan discovery step. It never states when NOT to use it or names an alternative tool, so it stops short of a 5.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is covered structurally. The description adds the auth prerequisite (free account required) and the returned fields, but says nothing about pagination, result limits, or what happens with zero sites.

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

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

Three short sentences, zero filler, with the core action and returned fields front-loaded and the prerequisite and use case trailing in priority order.

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

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

For a simple read-only list tool with no output schema, strong annotations, and fully documented parameters, the description covers purpose, use case and prerequisite adequately. Return-shape and pagination behavior are the only unaddressed items, and they are minor here.

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

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

Schema description coverage is 100% and both parameters (context, llm_model) carry detailed analytics-only instructions in the schema. The description adds no parameter guidance, which is acceptable given the schema does the work, but it contributes nothing beyond baseline.

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

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

The description names a specific verb and resource (list the sites on the signed-in account) and enumerates the returned fields (site id, plan tier, plan end date). It does not explicitly contrast with any sibling such as add_site, but the read-scoped account focus makes it distinguishable in practice.

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

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

It gives a concrete use case — 'check that a payment activated WebAbility Pro on a site' — and states a prerequisite ('Needs a free WebAbility account'). It stops short of naming alternatives or when-not-to-use conditions, so it is clear context without 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 only cover safety (readOnly, idempotent, closed world); the description adds substantive behavior: jsdom has no layout so contrast/target-size/focus-ring rules are skipped, the dropped count surfaces as skippedVisual, and the browser path is slower, axe-only, and returns violations instead of the normal shape.

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?

A single dense paragraph, but the key fact (in-process, no browser, no network) is front-loaded and each clause carries real information. Slightly heavy but nothing is filler.

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

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

With 12 parameters and no output schema, the description carries the return-value burden and largely discharges it by describing issues/summary, fix.op, fixability, skippedVisual, and the axe violations shape. Minor gaps remain around the analytics-only params, but the core call semantics are covered.

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

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

Schema coverage is 100%, so the baseline is 3, but the description enriches the engine parameter well beyond its schema text by tying it to which rules run and what output shape comes back (skippedVisual vs violations).

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

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

States a specific verb and resource: scan a raw HTML snippet/component markup without serving it. It also implicitly separates itself from scan_page by noting it returns scan_page's shape, letting an agent tell the two 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?

Gives clear when-to-use context — in-process is for a tight edit loop (milliseconds, no browser), and engine: "browser" is the escape hatch when visual-tier rules are needed. It does not explicitly say when to prefer scan_page over this tool, so no full alternative routing.

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

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

Annotations already cover readOnly/idempotent/openWorld/destructive=false, yet the description still adds substantial behavior: how violations vs judged[] vs dropped results are produced, the fix.op/fixability taxonomy, source pointers on React/Vue dev builds, and the hard constraint that the hosted server refuses localhost/private addresses. That last point materially changes how an agent must call the 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?

It is long and dense, but front-loaded with the core purpose and output shape, and the paragraphs each carry distinct information (returns, source pointers, fix ops, hosting limits, local alternatives). A few details duplicate the schema, keeping it from a 5.

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 complex 12-parameter tool with no output schema, the description fully explains the return structure (issues, summary, judged[], fix fields) plus the operational constraints an agent needs, leaving nothing critical to inference.

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 12 parameters are already documented in the schema itself. The description mostly restates schema semantics (tunnel_secret requirement, sourceRoot/sourceCandidates, url examples) rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource — scan a web page for WCAG accessibility issues — and the scope (any URL, deployed/localhost/staging) makes it distinguishable from siblings like scan_html, flow_scan, and visual_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?

Gives strong context: it works on deployed sites, localhost, and staging, and it spells out two workarounds (local MCP install or tunnel) when the hosted server refuses private addresses. It does not explicitly route the agent to a sibling (e.g. scan_html for markup-only or flow_scan for multi-step), so it stops short of full alternative coverage.

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 cover safety/open-world flags, and the description adds substantial behavior beyond them: async fire-and-return with an `id`, polling via get_audit, ~5 minute runtime, tunnel must stay open because the pipeline loads the page several times. This is exactly the operational context annotations cannot 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?

Front-loaded with what it produces, then usage routing, then setup mechanics. Dense but nearly every clause carries actionable information; the parenthetical sheet listing and pipeline component list are slightly heavier than necessary but still informative.

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 an async mutation-ish tool with no output schema, the description covers auth, async contract, polling target, runtime, tunnel requirements, and the return payload (id + download URLs). Nothing an agent needs to invoke it correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: includeAgent triggers a slower agentic pass, tunnel_secret is required only for tunnel URLs and otherwise ignored, and url must be server-reachable (not localhost). This enriches the two non-obvious parameters.

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

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

States a specific verb ('Kick off') and resource ('FULL accessibility audit deliverable for a URL'), and explicitly contrasts itself with an inline scan. It also names the exact sibling alternative (scan_page + verify_fix), so an agent can distinguish it without opening any schema.

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

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

Gives explicit when-to-use ('when someone needs a durable artifact to attach as evidence for a compliance officer or legal response') and when-not ('for iterating on code, use scan_page + verify_fix instead'). Prerequisites (free WebAbility account, sign-in path) and the tunnel workflow are spelled out.

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 cover the read-only/idempotent safety profile; the description adds far more: it fails closed (blocked page = unverified, never a pass), enumerates exact reason codes (not-found, not-verifiable, unsupported-selector) and the conditions producing them, and defines precisely when verified:true is returned. It also discloses the hosted-server network restriction, which annotations cannot 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 purpose is front-loaded and every clause carries actionable detail (reason codes, environment caveats). It is dense and long for a single block of prose, but little of it is filler, so the size is largely justified rather than padding.

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 7-param, no-output-schema, behaviorally intricate verification tool, the description covers return semantics, failure modes, scope boundaries, and environment constraints. An agent has everything needed to invoke it correctly and interpret the result without an 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 3 is the baseline, but the description adds real semantics: the wcag param's omit-vs-pass behavior (check one criterion vs require clean of ALL), and guidance that selector must be the element's current selector (re-run scan_page if it was removed). Minor gap: it doesn't discuss context, llm_model, or viewport semantics beyond matching the original scan.

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 opening sentence names a specific verb and resource ('Re-scan a specific element after applying an accessibility fix and confirm the violation is gone'). It distinguishes itself from siblings by explicitly scoping out visual_audit findings and positioning itself in the scan_page → generate_ai_fix → verify_fix cycle.

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 states exactly when to call it ('after you edit the code and serve it'), what to pass (URL + the selector you fixed), and names the alternatives/cycle it belongs to. It also flags a critical when-NOT condition: localhost/private addresses are refused on the hosted server, with two concrete workarounds (local MCP, tunnel + secret).

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 declare readOnly/openWorld/idempotent/destructive flags; the description goes far beyond by disclosing the auth requirement, fair-use rate limits, the cloud-vs-local reachability limitation, and the mechanism (headless browser screenshot then vision detection). 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?

Front-loads what the tool does and its differentiator before moving to prerequisites and the localhost/tunnel caveat. Dense but each sentence carries operational information; the numbered issue list is arguably slightly long but defensible.

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 no output schema and a 7-parameter openWorld tool, the description supplies the missing context: auth, rate limits, reachability, and local-dev workarounds. An agent has everything needed to decide and call 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 cross-parameter semantics by explaining that a tunnel URL must be paired with the printed secret as `tunnel_secret` and that the URL alone will be refused. It does not add much for viewport/fullPage/brandColors, hence not a 5.

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

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

States a specific verb+resource (pixel-level accessibility audit via vision) and enumerates the exact WCAG issues it catches, which distinguishes it from generic DOM scanners. It also explicitly positions itself against the sibling scan_page ('Complements scan_page — run both for full coverage').

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

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

Gives explicit when-to-use (issues DOM scanners miss), when-to-run-both (with scan_page), prerequisites (sign-in to WebAbility), and hard constraints (localhost/private addresses refused on hosted server). It even routes the agent to two concrete alternatives for local dev servers.

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