a11y_generate_declaration

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

Annotations are entirely absent, so the description bears the full burden of behavioral disclosure. It states the tool 'generates an HTML declaration' and that the HTML is accessible, but it doesn't disclose side effects such as whether it writes to a file (output_path), what the return value looks like, any permissions or prerequisites, or what happens when required fields are missing. The description only scratches the surface of 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 compact—two sentences—with the main purpose front-loaded and no filler. It efficiently conveys the legal compliance aspect and the output format. It loses a point because it omits usage guidance and parameter details that could be briefly integrated, but as a concise statement it is well-structured.

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?

This tool has 13 parameters and no output schema, but the description provides almost no context about how those parameters influence the generated declaration, what the required inputs are for, or what the output looks like beyond being HTML. With no annotations and no output schema, the description is grossly incomplete for an agent to correctly invoke this tool, especially given its complexity. It leaves the agent to guess at 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 only 15%, so the description must compensate for the undocumented parameters, but it barely does. It mentions 'marco="eaa"' inline, which clarifies that parameter, but it does not explain the meaning of entidad, url, estado, metodo, feedback, reclamacion, etc. The phrase 'Campos legales incluidos' suggests some legal fields are used but does not map them to the schema. The description adds almost no parameter semantics beyond the schema's minimal 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 tool generates an HTML accessibility declaration under two legal frameworks (RD 1112/2018 and EAA), using a specific verb ('Genera') and resource ('Declaración de Accesibilidad'). It distinguishes itself from sibling tools like a11y_audit_url or a11y_snapshot, which are about auditing or capturing, not generating declarations. However, it doesn't explicitly name any sibling alternatives, but 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?

There is no explicit guidance on when to use this tool versus the sibling tools. The description mentions the two legal frameworks (marco) which could hint at a usage condition (choose the appropriate framework), but it doesn't state scenarios like 'use this when you need a formal accessibility statement' or contrast with other tools. An agent would have to infer usage from the purpose alone.

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