a11y-toolkit: PDF accessibility screening

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

Annotations already declare readOnly/idempotent/non-destructive and closed-world, so the bar is met; the description goes further by stating it is a zero-dep structural first pass, operates only on local files and never fetches remotely, and enumerates which failure classes it detects versus which it cannot. That is real behavioral context beyond the structured fields.

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

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

Dense but front-loaded: the differentiator and file-locality constraint come first, then the check list, then the output shape. The parenthetical comparisons with axe/pa11y/Lighthouse and veraPDF are justifiable boundary-setting, though the sentence is long enough to approach overload.

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 names the returned JSON keys (mode, pages, tagged, lang, title, images, alt_entries, findings, summary, limits), so an agent knows what it gets back, and it clearly frames scope and limitations. Nothing needed to invoke or interpret the tool is missing.

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

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

Schema coverage is 100% and both parameters are documented in the schema; the description's only path-related guidance ('never fetched remotely — download it yourself first') duplicates the schema's own description nearly verbatim and adds nothing about the lang enum. 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?

States a specific verb and resource ('PDF accessibility screening' on a LOCAL file) and enumerates the concrete checks performed (tagged tree, title, language, outline, /Alt, text layer, encryption). It explicitly separates itself from the HTML-only tools and from spec validators like veraPDF, so an agent can place it without opening the schema.

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

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

Gives clear context ('enterprise document pipelines and PDFs linked from the audited site') and a boundary condition — full PDF/UA conformance belongs to a spec validator, not this tool. It stops short of naming any sibling tool (e.g. a11y_audit_url vs a11y_audit_dom) as the alternative for HTML inputs.

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