audit_screen

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

Annotations already declare the tool safe and read-only, so the bar is lower. The description counts credits by adding real behavior: no-arg self-documentation mode, platform-specific thresholds, and nuanced handling of Material/Android semantic colors as warnings rather than failures. It also links its return shape to audit_page.

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?

Five short front-loaded sentences, no filler and no repetition of schema constituents. Purpose, invocation, platform semantics, scored dimensions, and return-shape reference are each given exactly one sentence.

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-param tool with nested objects, no required params, and no output schema, the description is strong: it explains the input model via the no-args response and the return contract via audit_page. The only residual gap is scroll_settle and broader return-value detail, but those are partially covered by the self-documented protocol.

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 86%, so the baseline is 3 with no extra param info. The description still adds value: it explains what the platform choice actually changes, and the no-arguments invocation mode is a behavior absent from the schema. It does not clarify the otherwise undocumented scroll_settle, which keeps it below a 5.

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: 'Audit a rendered mobile screen (iOS or Android) from a view-hierarchy/accessibility snapshot.' It also enumerates what is checked — touch targets, contrast, and visual rhythm — so it is not confused with a single-purpose audit tool and identifies the operation precisely.

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 direct invocation guidance: call with no arguments to receive the snapshot shape and capture instructions, pass platform:'android' to change scoring semantics, and omit platform for iOS. It does not explicitly state when NOT to use this tool in favor of alternatives like the specialized audit_tap_targets or audit_contrast, but the context is clear.

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