analyze_accessibility

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

No annotations are provided, so the description carries the full burden of behavioral disclosure. It reveals performance implications (rescanning avoidance) and hints at output scope, but doesn't mention whether this is a read-only operation, whether it requires an existing session, what happens with invalid paths, or the cost/limits of analysis beyond the limit parameter.

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

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

Two sentences covering purpose, output scope, and usage preference. Efficient and to the point with no filler. Could potentially add a sentence about limit semantics but overall achieves maximum signal per word.

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 3 optional params, no output schema, and no annotations, the description is reasonably informative but leaves gaps. It doesn't explain the return format (counts as numbers? structured objects?), the relationship between sessionId and path (either-or vs both), or the meaning/effect of limit. The rescanning note is valuable but incomplete guidance for a tool with ambiguous alternatives.

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 0%, so the description must compensate. It explains sessionId vs path tradeoff (rescanning avoidance), which adds meaning to both. However, the 'limit' parameter is not explained at all in the description, and the interaction between sessionId and path (mutually exclusive? both optional?) is unclear.

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 returns accessibility analysis data from a review_project session or path, listing specific output types (semantics widget counts, tooltip usage, missing semantic labels). It distinguishes from siblings like analyze_code_quality and analyze_performance by focusing on accessibility, 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?

The description advises 'Prefer sessionId to avoid rescanning,' which gives clear practical guidance on parameter choice. However, it doesn't state when to use accessibility analysis vs other analyze_* tools, nor when sessionId isn't available and path should be used.

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