Inclusify Accessibility

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

The description discloses significant behavioral details beyond annotations: it 'WRITES to this website's Inclusify configuration, never to the site itself', touches no code/theme/DNS, does not make the hostname resolve, and explains primary domain behavior. These are important side effects and constraints that annotations do not capture.

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 dense but every sentence serves a purpose: when to use, what it does/doesn't do, constraints, primary-domain rule, and follow-up action. It is well structured and front-loaded with the most important usage guidance.

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 mutating tool with no output schema and no readonly annnotations, the description covers all necessary context: purpose, side effects, constraints, error refusals, primary-domain semantics, and the follow-up step to check widget installation. An agent has enough information to invoke it correctly and set expectations.

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 the description adds meaningful parameter semantics: the new hostname must share a name with existing domains, URLs are reduced to their host, and localhost/IPs are refused. This goes well beyond the basic 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?

The description states a specific verb and resource: 'add another domain to a website' and clarifies it applies to 'a site Inclusify already knows about' on 'ANOTHER hostname'. It explicitly distinguishes itself from add_website, making the tool's scope and 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?

It gives explicit when-to-use context: when a known site is reachable on another hostname. It also names the alternative, add_website, for 'a site Inclusify has never heard of', and lists refusal cases such as mismatched names, localhost, IP addresses, and domains registered to another account. This leaves no ambiguity about when to choose this tool.

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

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

Beyond the annotations (readOnlyHint=false, openWorldHint=true, idempotentHint=true, destructiveHint=false), the description adds significant behavioral detail: it writes only to configuration, not the site; idempotent behavior with 'alreadyMonitored' response; all-or-nothing batch semantics against the audited-page allowance; and async pickup via the scan worker's queue with a ~20h re-scan. 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?

Dense but well-organized: the usage trigger is front-loaded, then behavioral guarantees, constraints, and async caveats follow logically. Every sentence carries unique information; there is no filler or redundancy. The structure aids quick comprehension despite the length.

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 tool with no output schema, the description is remarkably complete. It covers write scope, idempotency, batch atomicity, page allowance, domain restriction, async pickup timing, and routes to alternatives. An agent can confidently decide whether to call it and what to expect, with no missing critical details.

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

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

Schema description coverage is 100% for both parameters, which already document full URLs vs paths, domain restriction, and maxItems=20. The description re-states the 20-per-call limit and domain requirement without adding new parameter-level insight. Per the rubric, baseline 3 applies when schema already does the heavy lifting, and no additional meaning is provided.

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

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

Clear verb+resource: 'adds URLs to the set of pages scanned on the daily monitoring rotation.' Explicitly distinguishes from siblings: 'Add-only: it never removes, pauses or edits a page' and 'for an immediate answer use start_crawl or a live check tool.' The purpose is unambiguous and directly tied to the tool's name.

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?

States exactly when to use ('a page that matters is not being watched at all — a checkout, an account area, a campaign landing page missing from list_monitored_pages') and provides explicit exclusions and alternatives: 'for an immediate answer use start_crawl or a live check tool.' Also clarifies that removal/pause/edit goes to the Inclusify panel, giving a complete when/when-not picture.

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 readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description goes far beyond these by detailing that it writes only to configuration, never to the site, that it is idempotent (no-op for existing domains), requires confirmation, enforces domain uniqueness, and refuses when workspace selection is ambiguous. 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 long but every sentence adds actionable information: usage conditions, precise scope, confirmation pattern, idempotency, edge cases, and limits. The most critical usage guidance is front-loaded ('Use this when...'), and the rest is dense with no redundancy. Length is justified by the tool's complexity.

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

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

For a tool with no output schema, the description fully covers what an agent needs: what it does, when to use it, the two-step confirmation flow, domain normalization, idempotent behavior, account limits, and workspace ambiguity refusal. Nothing essential is left unstated.

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 already covers all three parameters with 100% coverage, so baseline is 3. The description adds substantial meaning: explains why there is no 'website' parameter (because the website doesn't exist), clarifies the confirm token's purpose and lifecycle (10 minutes, works once), and describes domain normalization (full URL reduced to host, 'www.' dropped). This significantly enhances 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 states a specific verb ('registers a domain as a website') and resource ('account's Inclusify configuration'), and explicitly distinguishes from siblings by naming when to use it ('not in their Inclusify account yet') and what it does not do ('never to the site itself'). The purpose is unambiguous and clearly differentiates from add_domain and list_websites.

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 when-to-use conditions ('when the user names a site that is not in their Inclusify account') and a special case ('fills in an account registered without a website'). Also specifies the two-call confirmation workflow, refuses on multi-workspace ambiguity, and notes the 50-website limit. This gives complete routing and 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?

Beyond the readOnlyHint annotation, the description fully discloses behavior: it returns only a URL, does not create a checkout session, does not charge, and will return no link for invoice-managed customers. This level of detail prevents an agent from making false promises to the customer.

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 longer than average, but nearly every sentence carries meaningful caveats or routing guidance. It is front-loaded with the primary use case and then systematically addresses exceptions and side effects, though some redundancy around 'does not change a plan' could be trimmed.

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 there is no output schema, the description fully covers what is returned, the per-billing-type variations, the no-link case, and the read-only behavior. An agent has enough information to invoke the tool and handle the response correctly for each customer type.

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 schema already fully describes both parameters and their intended use. The description adds context about the overall return behavior but no additional semantic detail about the `plan` or `website` parameters beyond what the schema provides. Baseline 3 is appropriate.

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

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

The description states a clear action and resource: returns the correct URL for the customer's billing owner to change plans. It explicitly distinguishes itself from plan_options and clarifies it is 'just the door'. The purpose is unmistakable.

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

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

It gives explicit guidance on when to use this tool ('when the customer has decided to upgrade, downgrade or cancel') and when not to ('Use plan_options first if they are still deciding'). It also covers edge cases like invoice-managed websites where no link should be sent.

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 goes far beyond the readOnlyHint annotation by explaining exactly what it inspects (missing vs. empty alt, filename-as-alt, 'image of' opener, too-long alt, caption repetition, link-only content), what it deliberately excludes (decorative images, repeated alt), and edge cases like void runs and challengeSuspected. This level of detail leaves no misunderstanding about side effects or limitations.

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 lengthy but every sentence earns its place — it covers alternatives, costs, scope, exceptions, and edge cases in a logical order. It is front-loaded with the core purpose and read-only guarantee, then drills into specifics. While a bit verbose, it is not padded and remains scannable.

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

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

Given there is no output schema, the description fully compensates by enumerating all possible behaviors: the 20-finding cap with imageCount and findingsOmitted, the void-run handling, challengeSuspected logic, and the distinction between markup-decidable and semantic alt issues. An agent has everything needed to invoke 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 a 3 is baseline, but the description adds real value: it explains the vision-call cost and PRO-plan requirement for suggestAlt and the homepage default for url. These operational nuances are not in the schema and materially affect how the agent should call the 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?

The description opens with a specific, time-sensitive use case ('check one page's images and alt text NOW') and explicitly contrasts itself with list_alt_findings, making the purpose unmistakable. The verb 'check' plus the resource 'page's images and alt text' is precise and distinguishes 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?

It gives explicit when-to-use ('including a page no scan has ever covered, and straight after changing images'), when-not-to-use ('For what a stored scan already recorded... use list_alt_findings instead'), and even points to a sibling for a related but different task (screen_reader_transcript). The metering caveat further helps the agent decide whether the cost is acceptable.

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

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

Annotations already declare readOnlyHint and non-destructive, and the description adds substantial behavioral detail: failing verdict is a normal result not an error, unmeasured or incomplete scans fail the gate, and it judges only the recorded scan without loading pages. This prevents critical CI misbehavior like treating a failure as a retryable error.

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 information-dense but every sentence earns its place: use-case, criteria, failure semantics, no-scan caveat, page-count caveat, and read-only confirmation. It is front-loaded with the main purpose and then covers edge cases in a logical 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?

Given there is no output schema, the description sufficiently explains the returned verdict and critical behaviors: how to read the result, when it fails, what the page-count caveat means, and that no scanning occurs. It is complete enough for an agent to call this tool correctly in a CI 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?

The schema already documents all four parameters at 100% coverage, so the baseline is 3. The description adds the combination semantics ('any combination'), the default behavior when no criterion is supplied, and the fact that the response says so, which goes beyond the 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?

The description states a specific verb and resource: it produces a pass/fail verdict for a CI pipeline based on the last recorded accessibility scan. It distinguishes itself from general reporting tools by emphasizing the gate decision purpose and the verdict output.

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 explicitly says when to use it: in CI or a deployment pipeline when a build should be blocked or allowed based on accessibility. It does not name sibling alternatives or explicit when-not-to-use cases, but the intended context is clear and actionable.

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?

Although the annotations already indicate readOnlyHint=true, the description goes further: 'Read-only: costs one read and loads no page', and it discloses important limitations such as not holding per-criterion status and not being able to determine legal compliance. It also warns the agent not to infer or report legal conclusions, aligning with openWorldHint expectations.

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 dense and front-loaded with usage guidance, but it repeats some return-content details in the comparison with site_overview. Still, nearly every sentence serves a distinct purpose, and the length is justified by the need to disambiguate siblings and warn against legal misuse.

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 needs to explain the tool's return contents and boundaries, and it does so comprehensively: statement fields, scan counts, gap list, exclusions, and operational cost. Nothing needed for a single-parameter read-only 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?

The input schema already describes the only parameter, website, with an example. The description refers to 'one website' but adds no new parameter semantics beyond the schema, so baseline 3 applies.

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

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

The description specifies a precise documentary-evidence purpose and enumerates exactly what the tool returns: accessibility statement contents, scanning record, and a gap list. It also distinguishes itself from site_overview, score_history, and list_violations, making the tool's role unambiguous.

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

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

It gives explicit when-to-use cases, such as demand letters, procurement questionnaires, and conformance claims, and explicitly says when not to use it: if site_overview already answered whether a statement is live, or when per-criterion WCAG status or scan history is needed. It also names alternative tools for those cases.

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 readOnlyHint and openWorldHint annotations, the description discloses that the tool is read-only and does not spend page allowance, that it returns partial data if a crawl is still running or failed, and that a never-crawled site is reported as missing coverage rather than a clean result. These behavioral traits are not visible in the annotations and are critical for correct interpretation.

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

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

The description is front-loaded with the primary use case and explicitly warns about sample vs. full coverage early. While it is longer than a typical description, every sentence adds value—usage guidance, data fields, caveats, and sibling routing. It is structured logically without redundancy, so the length is justified despite being on the verbose side.

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 tool returns a complex summary with many fields, and there is no output schema. The description lists every data element (status, start URL, found/scanned counts, average score, totals by impact, run time, worst pages) and explains edge cases (failed/running crawls, never-crawled websites, sample limitation). It also routes to page_history for trends, making it fully self-contained for correct invocation and interpretation.

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%, with both parameters (website, worstPages) already clearly documented in the input schema. The description does not add extra semantics beyond what the schema provides—it mentions worst-scoring pages but does not elaborate on the worstPages parameter itself. Given the high schema coverage, the baseline of 3 is appropriate.

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

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

The description states a specific verb ('use this when the question is COVERAGE') and clearly enumerates exactly what data the tool returns: status, start URL, found vs scanned counts, average score, totals by impact, run time, and worst-scoring pages. It also distinguishes itself from siblings by naming page_history as the alternative for trends and start_crawl as the way to queue a crawl, so an agent can reliably separate it from other 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 when to use it ('when the question is COVERAGE... or to collect the outcome of a crawl you queued with start_crawl') and when not to ('For a page's trend over time use page_history'). It also instructs the agent to read it before quoting any site-wide number, giving a clear precondition. This is model usage guidance with 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 mark this as read-only and non-destructive, but the description adds important behavior beyond that: per-response options are read at collection time rather than at queue time, a job can be collected with more detail without a second browser run, and no page is loaded or charged.

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 first sentence front-loads the critical routing information, and every following sentence contributes non-obvious behavioral detail. There is no wasted prose; the description is dense but well organized.

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 trigger conditions, polling behavior, response equivalence, collection-time option semantics, and cost/charge implications. Because the payload is stated to be identical to the queued tool's inline result, the absence of an output schema is not a gap.

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

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

The schema fully documents all six parameters with a 100% coverage, so the baseline is 3. The description adds meaning by explaining the jobId contract and clarifying that the boolean per-response options are evaluated when the job is collected, which gives the agent a better mental model of how the parameters work.

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 action and resource: collect the stored result of a queued job. It names the exact four tools that can return a job id and clearly distinguishes this tool from inline result delivery.

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 explicitly says when to use the tool: when keyboard_walk, simulate_condition, screen_reader_transcript, or check_page_alt_text returned a job id instead of a result. It also tells the agent to retry after a few seconds if the job is still running and explains that no different parsing is needed because the payload is identical to inline.

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 goes far beyond the read-only annotation: it discloses confidence levels, pixel-based focus measurement, endedBy semantics, void runs vs challengeSuspected, viewport dependence, selector truncation, and modal-trap caveats. There is no contradiction between the description and 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 long but dense with non-redundant, operational details. It is front-loaded with the most important usage guidance and then systematically covers behavioral nuances, edge cases, and output semantics, so every sentence earns its place.

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

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

With no output schema present, the description fully compensates by explaining what findings look like, what endedBy values mean, how selectors and counts work, and how void and challengeSuspected runs are reported. It gives the agent everything needed to interpret results 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?

Although the schema already covers 100% of parameters, the description adds meaningfully to them: it explains that full does not re-walk the page and costs nothing, maxSteps interacts with a 45s budget and endedBy, url defaults to the homepage, and includeRing returns one entry per stop. This is substantial 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?

The description states a specific purpose: testing whether a site actually works for keyboard-only or switch-device users, covering tab order, focus traps, and visible focus indicators. It also distinguishes itself from stored scans and static markup checks, making the tool's unique value immediately clear.

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

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

It gives explicit 'Use this when' guidance, tells the agent to run it before claiming keyboard accessibility and again after tab-order or skip-link fixes, and explains why static checks can't substitute for it. This is clear selection guidance with no ambiguity.

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

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

Even though annotations already declare readOnlyHint and destructiveHint false, the description adds critical behavioral context: markupHint is a reconstruction, not scanned source; counts have a precise relationship with a warning against summing affectedImages; suggestedAlt is generated without page context and may not be the correct fix. This goes well 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 long but every sentence serves a purpose: usage routing, return contents, scope, markupHint caveat, count semantics and warning, suggestedAlt caveat, and read-only confirmation. It is structured in logical blocks with no filler, and critical usage guidance 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?

With no output schema present, the description carries the full burden of explaining the response. It covers field semantics (selector, current value, reason, suggested replacement), the markupHint reconstruction, the relationships among rawFindings/distinctImages/returned, the template grouping caveat, and the suggestionCaveat. This is comprehensive for a complex tool.

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

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

Schema coverage is 100%, with each of limit, status, and website already described in the input schema. The description does not add parameter-specific notes, but that is acceptable because the schema carries the parameter semantics fully. Baseline 3 applies.

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

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

The description opens with a specific use case ('subject is images — alt text, image descriptions'), states the resource and action ('list alt-text findings'), and names the sibling tool (check_page_alt_text) it is not. It goes beyond the title by enumerating the types of problems found (missing, filename-like, vague, inaccurate) and the scope ('most recent scan').

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 explicitly says when to use this tool ('across the whole site, from the scan already on record') and when to use the alternative ('For one page checked right now, including one no scan has covered, use check_page_alt_text'). It also notes the scope is the current scan, not history, leaving no ambiguity about selection.

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

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

Annotations already declare readOnlyHint=true, so the read-only statement is consistent and reinforced; the description adds useful behavior beyond annotations: it costs one read and loads no page, returns nothing for non-Shopify stores, and explains the special meaning of an empty result. 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 text is dense and front-loaded with the primary use case, then return payload, exclusion, and edge-case behavior. Minor redundancy exists in restating 'Problems found in the text' after the opening clause, but every sentence contributes useful routing or boundary 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 there is no output schema, the description compensates by enumerating what each finding carries (item, current text, reason, suggestion, confidence, admin link). It also covers expected empty results and scope limitations, making it sufficient for an agent to call 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?

The input schema documents all three parameters (limit, status, website) with descriptions covering 100%, so the schema does the heavy lifting. The description does not need to re-explain parameters and adds no new parameter-specific details, keeping this at the 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?

States a specific action ('list') and resource ('content findings') and immediately defines them as accessibility problems in merchant-authored words rather than theme code. It also explicitly separates itself from list_alt_findings, so an agent can disambiguate by text alone.

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 an explicit when-to-use condition ('when the accessibility problem is in the WORDS a merchant wrote rather than in the theme's code') and says when not to use it ('Do not use it for images or alt text — that is list_alt_findings'). It also warns about Shopify-only availability and the 'never reviewed' versus 'reviewed and clean' distinction.

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 readOnlyHint and destructiveHint annotations, the description discloses important behavioral traits: it loads nothing, costs no page allowance, adds/removes no pages, and shows the last recorded attempt rather than live site state. It also explains the ~20h monitoring cadence and the way silent failures can resemble clean sites, giving the agent deeper operational understanding.

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 longer than average, but every sentence earns its place: usage trigger, uniqueness, returned fields, slot reporting, read-only semantics, and cadence context. It is front-loaded with the most important usage guidance and contains no fluff or tautology.

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 one-parameter read-only tool with no output schema, the description is remarkably complete. It tells the agent when to call it, what data it returns, how to interpret empty results, what operational behavior to expect, and how to distinguish normal cadence from faults. Nothing essential 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%, and the schema already defines 'website' as the registered domain with an example. The tool description does not add new parameter-level meaning beyond that, so the baseline of 3 for high schema coverage 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 uses a specific verb ('lists') and resource ('monitored-page inventory for a website'), then enumerates exactly what is reported: watched URLs, paused pages, last scan time, last score, and failing/unreachable/throttled/overdue statuses. It also explicitly distinguishes itself as the only tool that reveals whether monitoring is actually working, separating it from siblings like list_websites or site_overview.

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 an explicit trigger: 'Use this whenever a scan-backed answer came back empty or thin and you need to know whether that means clean or never checked.' It further states this is the only tool that reports whether monitoring works, which excludes alternatives, and warns that recent scans being 'due' is normal rather than a fault, shaping correct interpretation.

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 goes far beyond the readOnlyHint/openWorldHint annotations by explaining aggregation by rule rather than page, capped selectors, distinctCauses as an upper bound, per-cause evidence, markupValidatable behaviour, scan coverage, and the fact that no pages are loaded. It explicitly frames the tool as not the whole audit and names what it cannot see, which is consistent with the openWorldHint annotation.

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 long but logically structured and front-loaded: purpose, grouping rationale, data fields, cause estimation, validation flow, scan scope, and exclusions. Some redundancy exists — 'no-page-load' and 'not the whole audit' appear more than once — but the density of decision-relevant detail justifies most of the length.

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 carries the full burden of explaining return values, and it does so thoroughly: totalElements, pages, examplePage, contrastData, grepFor, grepTargets, nextStep, distinctCauses, causes, markupValidatable, confirmWith, and scan are all described with their semantics. It also covers limitations, alternatives, cost implications, and the recommended follow-up tool, making it complete for an agent to invoke correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents all six parameters and the baseline is 3. The tool description adds useful behavioural context around caps and output fields that indirectly informs use of `full` and `limit`, but it does not directly add per-parameter semantics beyond what the schema provides.

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

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

The description opens with a specific use case — fixing, remediating, prioritising, or costing accessibility failures — and names the deliverable: a fix list from the current static scan. It clearly distinguishes itself from siblings by saying it is not for alt-text quality and not for render-only checks, naming list_alt_findings, keyboard_walk, simulate_condition, and screen_reader_transcript.

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 explicitly states when to use the tool ('Use this when the ask is to fix...') and when not to use it ('Not the tool for alt-text quality... Not the tool for anything only visible in a render...'). It also names the exact alternative tools for those cases and directs the user to validate_fix afterward, providing clear routing among siblings.

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

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

Beyond the readOnlyHint/openWorldHint/destructiveHint annotations, the description adds crucial behavior: an empty list is a legitimate response meaning no sites exist, not a permission failure, and the tool works on all plans including Free. This directly helps an agent 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?

The description is front-loaded with the most important usage instruction and every sentence contributes meaningful guidance. The trailing 'Read-only' slightly duplicates the readOnlyHint annotation, but the overall structure is efficient and well organized.

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 effectively covers return values by naming the fields and clarifies important edge cases: no sites, any plan, and empty-list semantics. The information is sufficient for an agent to call 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?

With zero parameters and full schema coverage, the baseline is 4. The description reinforces that no website argument should be passed, which is useful given sibling tools do take such arguments, though it adds little beyond the empty schema.

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

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

The description clearly states the tool lists every website in the account and specifies the returned fields: plan, last recorded score, and scan time. It distinguishes itself from add_website by explicitly saying it takes no website argument and by being the discovery-first 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?

It gives explicit timing guidance: call this first when you don't know which domains the account holds or when the question names no site. It also clarifies that it works on every plan and that an empty result is a valid answer, and points to add_website for creating a site.

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, and the description goes well beyond them: it discloses the dependency-based ordering logic, that plan-gated steps are named rather than dropped, that a missing scan is itself surfaced as a step, that the call executes no action and charges nothing, and that it costs roughly what site_overview's reads cost. This far exceeds what the annotations alone 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 long, but the length is earned: it must differentiate among 35 siblings and carry return-value details since there is no output schema. It is front-loaded, opening with when-to-use, then return shape, ordering, exclusions, and cost. A small amount of ground already covered by annotations (read-only safety) is restated, keeping it just short of 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 single-parameter tool with no output schema and heavy sibling overlap, this description is complete: it documents the return structure, the ordering principle, plan-dependent behavior, exclusions, sibling handoff, and cost. Nothing an agent needs to decide whether to call it or interpret its result 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 the schema already documents 'website' as the domain registered in Inclusify with an example. The description's 'for one website' phrasing aligns with the parameter but adds no format or value semantics beyond the schema, so the baseline of 3 applies.

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

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

The description states a specific verb and resource: 'Returns an ordered list of concrete next actions for one website.' It differentiates from siblings explicitly, naming list_violations as the owner of individual violations and clarifying it 'starts no scan,' which separates it from start_crawl and the finding tools without opening their schemas.

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

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

Gives explicit when-to-use triggers with customer phrasing examples ('what should I do', 'we just signed up') plus a workflow cue ('before writing any remediation or action plan'). It also tells the agent when NOT to use it: it lists no individual accessibility violations, routing those to list_violations and the other finding tools.

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

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

The description adds substantial behavioral detail beyond the annotations: it clarifies data comes from the 'last recorded scan,' results are 'worst impact first,' and findings are grouped by underlying pattern so one recurring root cause is presented as one problem. It also notes the ENTERPRISE plan restriction and read-only nature, all of which help an agent predict behavior.

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

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

The description is well-structured, front-loading the primary use case and then explaining aggregation and ordering. It is slightly wordy with illustrative phrasing like 'one template fault across forty pages,' but every clause contributes to understanding the tool's scope and behavior.

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 tool with one optional parameter and no output schema, the description adequately conveys what the caller will receive: accessibility findings grouped by pattern, worst impact first. It covers data source, grouping, ordering, and enterprise restriction, leaving no critical gap for correct 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?

The schema fully documents the only parameter, limit, including its default and cap, so the description doesn't need to add parameter-level detail. The description's mention of returning grouped patterns aligns with the parameter's purpose but adds no extra semantic 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?

The description clearly identifies a specific verb and resource: it finds cross-site accessibility patterns that can be fixed once across every website, grouped by shared theme, component, or colour token. It distinguishes itself from site-by-site remediation tools by emphasizing aggregated, pattern-level findings rather than individual findings per page.

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

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

The description explicitly states when to use it: to find a single high-leverage fix affecting multiple sites rather than remediating site-by-site. It doesn't name specific sibling tools as alternatives, but the 'rather than remediating site by site' contrast provides practical selection 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 indicate readOnlyHint, openWorldHint, and non-destructive behavior. The description adds useful context: it is an aggregate/rollup call ('one call instead of twenty'), works across all websites, includes never-scanned and overdue counts, and requires the ENTERPRISE plan. 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, each earning its place: when to use, what data comes back, and plan/read-only status. It is front-loaded with the primary use case and contains 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 covers the main return elements: per-site scores, average, and counts for unscanned/overdue sites. It is complete enough for a zero-parameter rollup tool, though it does not specify exact response formatting or mention the 'finding counts' from the title explicitly.

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 tool has zero parameters and the schema coverage is 100%, so there is no parameter-level burden on the description. The description adds value by explaining what the result contains, which is sufficient for a no-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?

The description clearly states what the tool does: returns the last recorded score for every website in the organisation, the average, and counts of unscanned or overdue sites. It also distinguishes itself from per-site tools by framing the scope as 'the whole portfolio rather than one site'.

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 explicitly says when to use it: for whole-portfolio accessibility questions, exec/board summaries, or identifying unscanned sites. It also gives a when-not signal ('rather than one site'), though it does not name a specific alternative sibling tool.

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

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

Even though annotations already declare readOnlyHint=true and openWorldHint=true, the description adds valuable behavioral detail beyond those flags: 'no page is loaded, no page allowance is spent', 'a fix deployed since the last scan does not appear', rule-level vs element-level counting, and the baseline-reporting behavior. These are critical for an agent to interpret results correctly and are not derivable from 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 longer than average but tightly packed—every sentence serves a purpose. It front-loads the primary use case and examples, then systematically covers output contents, counting semantics, edge cases (baseline, crawl exclusion), and read-only nature. No redundancy or filler; each clause 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?

With no output schema, the description fully specifies what the tool returns: score, violations by impact, count of fixed/introduced issue types, and ordering (newest first). It also covers the baseline quirk and the handling of crawl-only URLs, plus the clarifying note that a deployed fix won't appear. An agent has everything needed to call and interpret this 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% (all params have descriptions), but the description still adds meaning beyond the schema: it explains URL normalization ('Trailing slash and www do not matter'), clarifies the default and max for limit, and describes the output semantics (rule-level counts, baseline lacks new/fixed figures). This goes well above the baseline expected when schema covers everything.

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 precise scope: one URL over time, with concrete example use cases ('did my fix actually work', 'when did this page break'). It names the sibling tool (score_history) to differentiate, making it clear this is the per-page counterpart, not the per-site one.

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 opens with 'Use this when the question is one URL over time' and provides an explicit alternative: 'use score_history for the whole site.' It also specifies exclusion conditions (full-site crawl rows) and clarifies the baseline behavior, leaving no ambiguity about when to invoke this tool.

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

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

Annotations only say the operation is read-only and open-world, so the description carries the burden of behavioral detail. It explains that data comes from 'Inclusify's live configuration rather than remembered', tells the agent not to quote a price from memory, and discloses that invoice-managed sites cannot self-serve upgrade. This goes well beyond the structured annotations without contradicting them.

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

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

The description is fairly lengthy but front-loaded with immediate use cases, then product details, then a key behavioral warning about not quoting prices from memory. Every section contributes distinct value, though it could be tightened slightly without losing meaning.

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

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

For a tool with no output schema, the description is remarkably complete: it specifies the full return set (every plan, price, visitor allowance, audited-page allowance, feature list), explains that current plan usage is also returned, and reveals the billing-ownership nuance. An agent has enough information to use this tool correctly in a wide range of plan-related questions.

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 has one parameter and 100% schema description coverage, so the schema fully documents the parameter. The tool description does not discuss the parameter, which is fine given the high coverage baseline, but it adds no additional meaning about how to populate or format it.

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

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

The description clearly identifies this tool as the resource for any question about plans, pricing, limits, and upgrading, with concrete examples like 'what plan are we on' and 'how many pages do we get'. It also distinguishes itself from generic plan tools by emphasizing it returns live configuration data and current usage allowances, making its scope unmistakable.

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

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

The description gives explicit trigger conditions: 'Use this for any question about plans, pricing, limits or upgrading' and 'Also use it after any tool refuses on a plan gate.' It does not explicitly name sibling alternatives or state when not to use it, but the examples and the post-refusal use case provide clear contextual 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?

The description goes well beyond annotations, explaining that it writes to Inclusify configuration only, never to the site itself, does not change the domain, applies immediately, requires no confirmation, is reversible, and that a no-op call produces a specific response. This matches idempotentHint=true and does not contradict any annotation.

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

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

The description is front-loaded with the core purpose and then uses each sentence to eliminate a common misconception: no domain change, no visitor-visible effect, no routing change, use add_domain for hostnames, idempotent, reversible. Despite its length, every sentence contributes 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?

For a two-parameter, simple mutation tool with rich annotations, this description covers when to use it, what it affects, what it does not affect, how to handle the alternative case, and what happens on redundant calls. Nothing needed for correct invocation is missing, and no output schema is required.

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 meaningful context beyond the schema by clarifying that everything is addressed by domain rather than by name, and that the name parameter is only a display label that cannot move or redirect the site. This supplements the schema's descriptions rather than merely repeating them.

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 ('rename') and clear resource ('a site's display label inside Inclusify'), and immediately contrasts itself with add_domain. An agent can distinguish this tool from every sibling without needing to inspect schemas.

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

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

It explicitly states when to use the tool ('tidying up a default name, or matching a rebrand') and gives a direct alternative: 'To point Inclusify at a different or additional hostname use add_domain instead — renaming will not do it.' This leaves no ambiguity about 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?

Although readOnlyHint=true already signals a safe read, the description adds substantial behavioral context: it loads no page, costs no page allowance, knows nothing newer than the last monitoring scan, explains that a day with one page scanned is not comparable with a day with ten, and explicitly states that missing scans produce a 'missing data' message rather than a clean result. 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 dense and front-loaded, starting with the key decision rule ('about TIME') before details. Every sentence adds information; however, the final section on daily monthly series is somewhat long and could be tightened. Overall, it earns its length because it packs rare and valuable guidance.

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 (two time axes, plan-dependent availability, single-page vs site aggregation, sibling crawl_summary), this description covers all major operational edges: what data exists, what the points mean, how to request monthly data, what is excluded, and how missing data is signaled. No output schema exists, but the description explains the response semantics (direction of travel and change over window) sufficiently.

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 schema already documents all five parameters; the description therefore only needs to add meaning. It does so for the key decision parameters (days vs months vs granularity, url for single-page trend, the per-day mean behavior). The only slight miss is that the description does not restate every parameter, but that is unnecessary given the high schema coverage.

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

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

The description opens with 'Use this when the question is about TIME rather than the site's present state' and immediately names the resource (accessibility score over time) plus what it does not do ('it names no violation and locates nothing'). This clearly distinguishes it from sibling tools like list_violations, crawl_summary, and site_overview, so an agent can select it correctly without opening schemas.

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

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

The description gives explicit when-to-use ('about TIME rather than the site's present state'), explicit when-not-to-use ('Full-site crawls are excluded (see crawl_summary)'), and behavioral caveats ('cannot confirm a fix deployed minutes ago'). It even explains how to choose between daily vs monthly granularity, eliminating ambiguity.

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

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

Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds substantial behavioral context: it models Chromium's accessibility tree rather than recording specific screen readers, it reports bot-protection interstitials as void rather than clean, and it explains the challengeSuspected fallback when the title contradicts the read tree. These details go well beyond the annotations and help an agent 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?

The description is dense but well-organized, front-loading the primary use case and then layering caveats. Every sentence earns its place, but it is long and somewhat technical; a slightly more compact phrasing could improve scannability. The structural separation of the key distinction (rule checks vs sense read-aloud) is effective.

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

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

Given the tool's complexity — multiple modes, output variations, void/interstitial handling, and the cognitive model of how screen readers linearize content — the description is remarkably complete. It covers what the tool returns, what it does not (exact phrasing ground truth), how to interpret void runs, and when to enable includeNodes. No output schema exists, so the description appropriately carries the burden of explaining return behavior and does so thoroughly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds meaningful context for the mode parameter ('reading' vs 'rotor' vs 'both') and the includeNodes parameter (structural findings are always included, nodeIds capped to 5 examples). It also clarifies that maxNodes truncation is always reported. However, it doesn't add much beyond the schema for url/website, and the description doesn't explain the default homepage behavior for url — though that is in 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 starts with a specific, actionable use case — determining whether a page makes sense read aloud — and contrasts it with rule-checking, which distinguishes this tool from sibling tools like check_page_alt_text and list_violations. It also clearly names the resource (screen-reader transcript) and what it produces (announcements in order, roles, names, states and hints).

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

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

The description explicitly states when to use this tool ('when the question is whether the page still makes SENSE read aloud') and when not to rely on it ('do not treat the exact phrasing as ground truth' because it models Chromium's accessibility tree, not NVDA/JAWS/VoiceOver recordings). It also explains that stored scans don't hold this data, so no alternative tool can substitute, and it names the read-only nature.

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

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

Goes well beyond the annotations: explains exactly what is written and what is never touched, why confirmation is required (misrouted work to a team that didn't ask for it), that the account owner is emailed a record including the previous key, and that a PRO plan is required. Nothing contradicts readOnlyHint=false or destructiveHint=true; the one-use confirmation token sits in mild tension with idempotentHint=true, but the schema documents that token explicitly and the underlying end-state change is 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?

Around 180 words — long, but every sentence carries distinct information (when, what, exclusions, confirmation rationale, notification, plan gate) and the usage guidance is front-loaded. The density is justified for a destructive config tool with a two-step confirmation flow and several refusal conditions.

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 3-parameter tool with no output schema, the description covers preconditions (PRO plan, connected workspace), the exact effect and non-effects, the confirmation flow, failure modes (refusal when unconnected, inability to list projects), and post-change notification. An agent has everything needed to decide, invoke, and recover from edge cases.

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 schema itself is unusually detailed (domain format with 'example.com', project key with 'ACC'/'WEB2' examples, explicit warning against display names, case normalisation, and the full two-call confirm-token workflow). The description reinforces the projectKey semantics by noting the tool cannot list projects, but adds no new parameter-level detail, 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?

The description states a specific verb and resource (records the Jira project key exports should use, in the Inclusify configuration) and immediately draws the boundary: it 'never' writes to the site or to Jira and 'files no tickets by itself,' which cleanly distinguishes it from any ticket-creating sibling. The title 'Choose which Jira board this site's tickets are filed on' reinforces exactly the outcome the tool produces.

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?

Opens with an explicit when-to-use ('when the user wants accessibility findings exported from a site to go to a different Jira project, or is setting one up for the first time') and gives clear when-nots: it refuses until Atlassian is connected and cannot enumerate projects, so the agent must ask the user for the key. It routes around alternatives (browser OAuth flow, reading the key off the board) but stops short of naming sibling tools, which keeps it from 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?

Goes well beyond the annotations: discloses that it is a write to configuration, requires a two-step confirmation, and emails the previous recipient with an undo link. It explains why these behaviors exist (consequences of turning alerts off), which the annotations do not 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?

Although long, every sentence serves a purpose—purpose, side effects, confirmation, and sibling distinction are all covered without redundancy. The structure fronts the usage guideline, then details, then exclusions.

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 mutation tool with a confirmation requirement and side effects, this description is fully sufficient. It covers the confirmation workflow, the undo notification, and what the tool does not do, leaving no gap for the agent.

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 the description adds relational meaning: it explains the empty-string email behavior, that omitted params are left unchanged, and the confirm token lifecycle. These enrich the parameter understanding 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?

The description clearly states the resource (monitoring settings) and the actions (change where email goes, stop/restart alerts). It also explicitly differentiates from the sibling add_monitored_pages, leaving no ambiguity about 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?

Opens with 'Use this when the user wants...' and provides concrete use cases (routing to shared inbox, quietening during rebuild). It names the alternative tool for a different task and explains the confirmation flow, making when and when-not to use it explicit.

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 mark this as readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description goes far beyond those: it discloses that it WRITES to configuration, deliberately POSTS a test message before saving, explains failure semantics (if post fails, nothing is saved and reason returned), requires confirmation, and notes the PRO plan requirement. It also explains that first-time binding uses defaults while subsequent changes keep settings. No contradictions with annotations.

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

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

The description is long but every sentence carries functional weight: usage trigger, write target, cannot-do limitations, deliberate post behavior, failure handling, confirmation requirement, settings preservation, sibling pointer, and plan requirement. It's front-loaded with the primary purpose and then methodically covers constraints. Slightly verbose but not padded; a more compact version would risk losing nuance.

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

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

For a tool with three parameters, no output schema, and no nested objects, this description is exceptionally complete. It covers when to call, prerequisites (Slack connected, PRO plan), interaction flow (ask for channel, confirmation token), failure behavior, side effects, and relationship to a sibling. An agent would know exactly how to invoke this correctly and what to inform the user about.

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 each parameter already has a clear description. The tool description adds meaningful context: channel names are passed exactly as given and will cause refusal if unreachable; the confirm token is a two-step flow with a 10-minute validity and single-use; website must be registered in Inclusify. This goes beyond the bare schema, though most of the parameter meaning is already in 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 opens with a clear, specific purpose: 'Use this when the user wants accessibility alerts for a site to go to a Slack channel, or to a different one than now.' It distinguishes itself from the sibling set_slack_events by explicitly stating it controls the destination, not the event types. It also clarifies the resource (Inclusify configuration, not the site) and the side effect (writes to config, posts to Slack).

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 when-to-use guidance ('when the user wants accessibility alerts for a site to go to a Slack channel...') and clear exclusions: it cannot install Slack (must already be connected), cannot list channels (agent must ask the user), and requires confirmation. It also points to the alternative: 'Use set_slack_events to change which alerts fire.' This leaves no ambiguity about selection.

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

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

Beyond annotations, it discloses side effects precisely: writes to Inclusify configuration only, never posts to Slack, no confirmation needed for enabling, confirmation required for disabling or raising the threshold, and the PRO plan requirement. This matches and enriches the destructiveHint and readOnlyHint 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 dense but every sentence contributes: purpose, triggers, side effects, merge behavior, prerequisite, confirmation rules, and plan constraint. It is front-loaded with the key distinction from set_slack_channel and uses focused emphasis 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-parameter mutation tool with no output schema, it covers all essential operational context: preconditions, side effects, merge semantics, confirmation flow, and plan gating. The schema covers parameter details, so an agent has enough to select and invoke 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 adds valuable semantic clarity by grouping the parameters as 'four independent switches plus a threshold, all optional' and stating 'anything you leave out stays as it is,' plus which changes require confirmation. It doesn't detail each parameter individually, but the schema already covers those details.

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 action and resource: it decides which kinds of finding get announced to Slack by writing to the site's Inclusify configuration. It also differentiates itself from the sibling set_slack_channel by saying it operates 'once a channel is already chosen.'

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 concrete triggers ('to quieten somewhere noisy, or to switch on something a team keeps missing'), a prerequisite ('use set_slack_channel first, and this refuses until then'), and a plan requirement. This tells an agent when to invoke it and what must be true first.

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, the description discloses critical behaviors: publishing is refused with an itemized list if incomplete, republishing an already-published statement is not a no-op, withdrawing makes the URL return 404, confirmation is required in both directions, and the account owner is emailed with an undo link. This is far more than annotations alone provide.

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

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

The description is long but front-loaded with purpose and every sentence contributes necessary operational or safety context. For a high-risk legal publishing action, the density is justified and well organized.

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 output schema, the description fully covers the calling sequence, failure modes, confirmation requirements, side effects, and plan constraint. An agent has everything needed to invoke it correctly and handle the outcome responsibly.

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 the description adds substantial meaning beyond the schema. It explains the confirm parameter's preview/token flow, the published parameter's exact publish/withdraw and 404 consequences, and the website domain format. This makes the parameters far more actionable.

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 and resource: publishing or withdrawing an already-written accessibility statement at its public URL. It clearly distinguishes this from writing statement content and from modifying the website itself, so an agent can tell exactly what the tool is for.

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 explicitly states when to use the tool ('when the user wants the accessibility statement ... to go LIVE ... or wants to take it back down') and what it does not do (does not write the statement content). It also gives a precise two-call confirmation workflow and plan requirement, leaving little ambiguity.

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

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

Beyond the annotations, the description discloses critical behaviors: it writes to configuration not site code/theme, works via edge-cache purge within a minute, requires confirmation, emails the owner with an undo link, and warns that removing profiles is consequential. It also explains the complete-replacement semantics of enabledProfiles and the Enterprise-only hideBranding restriction. 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 long but densely informative, and the primary use case is front-loaded. It could be tightened, but nearly every sentence adds a necessary constraint or behavioral note, so it earns a solid score rather than being penalized for its length.

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

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

For a tool with 12 parameters, no output schema, and a destructive mutation, the description covers all essential invocation context: plans, Shopify exclusion, confirmation workflow, replacement-list semantics, undo email, and the distinction from set_widget_enabled. An agent has enough information to call it correctly and safely.

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 meaning beyond the schema: it frames enabledProfiles as consequential because removing a profile affects relying visitors, states that the preview names each removed profile, and clarifies that omitted settings are left unchanged. This enriches parameter understanding without replacing the schema's own detailed 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 states a specific verb and resource: 'Use this when the user wants the Inclusify widget on their site to look different' and 'or to change which accessibility PROFILES it offers visitors.' It clearly distinguishes this from set_widget_enabled and other sibling tools by covering appearance and profile changes specifically.

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

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

The description gives explicit when-to-use guidance, plan requirements, Shopify-billed store exclusion, and names the alternative tool: 'To turn the widget off entirely, use set_widget_enabled instead.' It also details the confirmation flow, so an agent knows the correct call sequence.

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

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

The description adds substantial behavioral detail beyond the annotations: it writes only to configuration, never to site code or theme; it purges the edge cache; turning off is destructive and requires confirmation; it emails the account owner with an undo link; and the operation is idempotent with a no-op response. This far exceeds what the annotations alone 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 longer than minimal, but every sentence carries important operational information: scope, effect timing, confirmation requirement, email notification, and idempotency. It is dense rather than padded, though it could be slightly more structured with headers or bullet-like separation for the two directional flows.

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 mutating tool with no output schema, the description covers the critical behavioral context: what is written, what is not touched, how confirmation works, what happens on no-op, and what side effects occur. It does not describe the exact response payload on success, but the two-call flow and preview mechanism are sufficiently explained for correct 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?

The schema already documents all three parameters with high coverage, so the baseline is 3. The description adds meaningful workflow context around the enabled and confirm parameters, especially the two-call confirmation flow and the idempotent behavior, which goes 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 action: switch the Inclusify accessibility widget on or off for a site, and targets the Inclusify configuration rather than code or theme. It also distinguishes itself from the similar sibling set_widget_appearance by focusing solely on enabled/disabled state.

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 when to use the tool: when the user asks to toggle the widget on or off. It also provides precise procedural guidance for the off direction, including calling without confirm first, showing the preview, and calling again with the confirmation token. This is strong usage guidance beyond the schema.

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 carry readOnlyHint=true and destructiveHint=false, and the description aligns with them ('Read-only'). It adds substantial behavior beyond the annotations: conditions that cannot be applied are 'reported as skipped rather than passing silently,' a bot-protection interstitial yields a 'void' run never presented as clean, and the challengeSuspected trust-the-findings logic. These are genuinely useful, non-obvious runtime traits. 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?

Purpose and usage are front-loaded well, but the description is very long and dense, descending into edge cases that could be trimmed — the count-vs-distinctSelectors markup-repetition aside, the challengeSuspected interstitial logic, and the detailed void-run accounting. Every sentence adds some value, but overall scanability suffers from the length.

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 must carry the return-value burden, and it does so thoroughly: it documents the selectors array (up to 5, count as true total, selectorsTruncated, full:true behavior), viewport reporting for reproducibility, and the void-vs-clean run distinction. For a tool of this complexity (5 params, rich behavior), nothing an agent needs to call or interpret 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?

Although schema coverage is 100%, the description adds deep semantics the schema lacks: it explains the conditions enum behavior (viewport widths 320px/390px/1280px, geometric vs pixel-based checks), and crucially that full:true 'reads from the result this run already stored — it does NOT load the page again and costs nothing against any allowance,' resolving selectorsTruncated without spending a second check. This materially changes how an agent would invoke the 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?

The description names a specific verb and resource — simulating a disabling condition on a page — and enumerates all four conditions verbatim (forced-colors, zoom-400, reduced-motion, target-size) with one-line definitions of each. It differentiates itself from static scanners ('structurally blind to'), so an agent can clearly tell what this tool does and how it differs from sibling tools like list_violations or keyboard_walk.

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?

Strong inclusion criteria: 'belongs in any thorough accessibility audit or remediation plan, not only when someone names zoom or tap targets,' with an explicit warning that skipping it means low-vision, magnifier and mobile users were not considered. It gives clear when-to-use guidance but never names a specific alternative tool or states exclusion conditions, and no direct sibling competitor is called 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?

Beyond the readOnly/openWorld/destructive annotations, the description adds substantial behavioral context: it costs one read, loads no page, reports only what is on record, explains that an unscanned site returns no score rather than a good one, and clarifies that a null score is never equivalent to 'never scanned' because scoreNote explains the reason. This is rich, non-redundant disclosure.

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 fairly long but front-loads the core purpose and usage guidance, then organizes caveats and plan-specific behavior logically. Some redundancy exists around the Free plan/no-scan-data case, but the length is mostly justified by the need to explain nuanced missing-score semantics and coverage meaning.

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 there is no output schema, the description carries the burden of explaining return values and does so thoroughly: plan, score and timestamp, page counts, visitor counts, statement status, widget state, scan blockers, coverage meaning, and null-handling semantics across plans. An agent has enough information to correctly invoke and interpret the tool.

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

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

Schema description coverage is 100% and the sole parameter 'website' is already documented as 'The website domain as registered in Inclusify, e.g. "example.com"'. The tool description does not add further meaning about the parameter itself, so the high-coverage baseline of 3 applies.

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

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

The description states a specific verb and resource: it is the starting point for accessibility/a11y/WCAG/ADA questions about one website and gives an overall current-position summary. It clearly differentiates itself from finding-level and detail tools by saying it reports counts and never individual violations.

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 explicitly says 'Start here' for any website whose current state is unknown, calls itself the cheapest way to learn what has been measured, and directs the agent to 'use the finding-level tools for detail' and to avoid using it to list problems. This is strong when-to-use and when-not-to-use 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?

Adds substantial context beyond the annotations: async job-return semantics, conditional retry safety (no duplicate crawl when PENDING/CRAWLING), maxPages clamping behavior, zero page-allowance cost, and the 3-crawls-per-day UTC limit. The 'writes to config, never to the site' and 'removes and edits nothing' statements align with destructiveHint=false and readOnlyHint=false with 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?

Though lengthy, every sentence carries distinct decision-relevant information: trigger condition, write-target boundary, clamping behavior, async pattern, retry safety, non-destructiveness, and rate limit. The most important usage guidance is front-loaded before implementation details.

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

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

Comprehensive for a complex async tool with no output schema: it explains what the call returns (job id immediately), how to obtain outcomes (crawl_summary, list_violations), resource costs, retry behavior, and rate limits. 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. The description mostly restates what the schema already documents about website domain format and maxPages clamping; it adds little new semantic meaning beyond reinforcing that the cap is the plan's audited-page allowance.

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: 'queues one full-site accessibility crawl' writing to the Inclusify configuration, never the site itself. The concrete trigger examples ('one page scanned out of eighty discovered, or a site never crawled') make it distinguishable from single-page scan tools and from result-reading siblings like crawl_summary.

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?

Opens with an explicit when-to-use condition: stored scan coverage is insufficient AND a site-wide audit was requested. It also routes follow-up behavior to named siblings (crawl_summary for progress/coverage, list_violations for findings), giving the agent a complete workflow path.

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 say readOnlyHint=true and destructiveHint=false, and the description reinforces this with 'Read-only — it does not touch the site, the scan history or the findings.' It adds substantial behavior beyond annotations: no page load, 100KB cap, refusal rather than guessing, the meaning of 'masked', and the four possible verdicts. There is no contradiction with 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 front-loaded with the primary use case and is densely informative, with almost every sentence earning its place. It is quite long and would benefit from bulleted or sectioned structure, but the complexity of the tool justifies most of the length and there is little true 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?

There is no output schema, so the description must and does explain return values: the four verdicts, what 'masked' means, and that failures name the remaining issue. It also covers limitations, prerequisites, size caps, and the rule-parameter requirement, making it complete for an agent to select and invoke 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?

Even though schema coverage is 100%, the description adds critical cross-parameter semantics: 'finding' can carry rule/before/colors, explicitly passed values override stored ones, 'before' enables deletion/lost-text detection, and 'colors' enables WCAG contrast arithmetic. These nuances are absent from the schema and materially change how the tool is invoked.

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 names the verb (validate), resource (an accessibility fix's markup), and intended moment (before deploying, after editing). It distinguishes this tool from the sibling list/set tools by focusing on verdicts like 'resolved', 'masked', and 'not_decidable_from_markup', so an agent can confidently pick it.

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

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

It gives explicit when-to-use guidance ('every time, on every rule, not only when you are unsure') and when-not-to-use guidance: check 'markupValidatable' first, and rendering-dependent checks are refused. It also connects to list_violations findings and tells the agent how to invoke with a findingId, making the call path unambiguous.

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

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

Beyond the annotations (readOnlyHint, openWorldHint, destructiveHint), the description discloses it does not fetch the site or check the page, returns the script tag when nothing has reported, and is read-only with 'three indexed reads, no page load.' The enabled flag caveat and lack of switching capability are also transparent, fully covering behavioral nuances.

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 long but every sentence delivers value: usage, distinctions, behavioral caveats, and read-only note. It is front-loaded with the purpose and usage, and the length is justified by the tool's nuance. Could be slightly tightened but remains 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?

Despite no output schema, the description explains exactly what facts it returns, when it returns a script tag vs. app embed advice, and what it doesn't do. Given one parameter and no output schema, it covers all necessary context for an agent to use 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% (the param description is already in the schema). The tool description does not add extra semantics for the 'website' parameter beyond what the schema provides, so the baseline of 3 applies.

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

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

The description states a clear verb+resource: it answers questions about the widget itself, distinguishing from accessibility findings. It provides concrete example queries and names the two separate facts it returns, making its purpose unambiguous and distinct from sibling tools like site_overview and the finding tools.

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

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

Explicitly states when to use it (questions about the widget) and when not (accessibility findings, site checks). It also mentions alternatives: site_overview and the finding tools own those concerns, and clarifies it cannot see an embed not yet visited. This leaves no doubt about proper selection.

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

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

Beyond the annotations (readOnly, openWorld, non-destructive), the description adds substantial behavioral detail: it is read-only and costs one read, loads no page, dedupes per feature per page view, and reports zero results with four possible causes. It also cautions that a zero total cannot distinguish between no feature use and an outdated widget build, and warns never to present an empty result as evidence of non-use. 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 long and detailed, but every sentence contributes meaningful context—ranging from use-case justification to return semantics and gotchas. It is front-loaded with the tool's purpose and the critical reading-before-use context. While it could be trimmed, the depth is warranted given the high risk of misinterpretation and misuse.

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 exceptionally complete for this tool's complexity. It explains what the tool returns (per-feature counts, deduping, totals, visitor count), how to interpret zeros (with four causes and their nuances), and explicitly addresses common pitfalls and misuse cases. With no output schema, the description fully compensates and more.

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?

Both parameters (days, website) are fully described in the input schema with clear meanings and ranges. The description does not add parameter-specific detail beyond the schema, though it does clarify output interpretation (unit is page views, deduping, zero handling) which indirectly affects understanding of the 'days' parameter results. Baseline 3 is appropriate since schema coverage is 100%.

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 reports accessibility widget usage per feature and page view, with explicit details on what metrics are returned. It distinguishes itself from sibling tools like site_overview by noting it measures visitor behaviour, not site accessibility, and even names the alternative for accessibility judgments.

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

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

The description gives explicit when-to-use context: 'before writing ANY remediation plan for a site where site_overview reports widgetEnabled: true', and lists specific query intents like 'is anyone using this' and 'before a renewal or cancellation conversation'. It also states when not to use it ('Do not use it to judge whether the site is accessible') and points to alternatives (site_overview and finding tools).

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