analyze_control_names

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

With no annotations, the description carries the full burden. It hints at non-destructiveness ('Advisory') and a report-like output, but does not disclose side effects, input processing behavior, or output format. The 'advisory' wording suggests read-only, yet this is not confirmed.

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

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

The description is a single sentence with no wasted words. It front-loads the core purpose and immediately conveys the tool's advisory nature. Strikingly concise and to the point.

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 in an accessibility suite with sibling analysis tools, this description is thin. It does not explain the expected output structure, the relationship to sessions, or how it fits into the review workflow. Agents cannot predict the return value or know when to rely on it.

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 50% coverage (url_or_html is described, session_id is not). The tool description adds nothing about parameters—no mention of how url_or_html is used or the role of session_id. It fails to compensate for the half of parameters left undocumented.

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 ('analyze' via 'inventory'), a resource ('control names and roles'), and a clear intent ('for human review'). It distinguishes from sibling analysis tools by focusing on 'repeated' instances, though it doesn't explicitly name alternatives.

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 guidance on when to use this tool versus any sibling, no context on prerequisites (e.g., session), and no mention of when it is appropriate to invoke. The phrase 'for human review' implies it feeds into a review workflow, but that link is not made explicit.

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