overlay_scan

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

No annotations are provided, so the description carries some burden. It discloses that scanning is a static snapshot, mentions the risk of transient overlays disappearing, and describes returned fields. However, it does not mention side effects (though it's presumably read-only) or exact visibility/box semantics; still, it adds useful behavioral context.

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 concise and front-loaded with the main purpose, then scope semantics, then return summary, then routing guidance. Each sentence adds value; the final sentence is a helpful warning. Slightly longer than necessary but 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?

Given the complexity of overlay scanning across iframes, the description covers the core selection logic, return summary, and the transient-overlay caveat. It lacks explicit mention of max_results bounding and exact 'active iframe' definition, but the output schema and defaults help. Overall sufficient for an agent to decide and invoke.

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%, and the schema only lists scope and max_results with defaults. The description explains scope values ('active' vs 'all') and max_results is not mentioned by name but is implied by '每个浮层' and '最多'? Actually max_results is not described; the description partially compensates for scope but not max_results. No parameter descriptions in schema, so baseline is low, but the description covers scope meaning partially.

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 ('扫描') and resource ('Ant Design Portal / ARIA 浮层') within the current visible page, and clearly distinguishes the scopes. It also separates this tool from sibling overlay_observe and ui_analyze_scope by specifying it targets portals/ARIA overlays.

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 explicitly explains when to use scope=active vs scope=all, and provides a concrete 'when not to use' for transient message/toast by directing to ui_click or vtable_cell_click(observe_after=True). This is strong usage guidance.

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