get_visual_map

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

No annotations are provided, so the description carries the full burden. It discloses that a screenshot is captured with numbered overlays, implying a read-only screenshot operation. However, it does not mention potential side effects such as file saving for the 'path' parameter, full-page scrolling for 'fullPage', or whether the result is returned as a file path or inline image. This partial disclosure is adequate but leaves gaps.

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 three short sentences, front-loaded with the core purpose, and includes actionable guidance about click references. Every sentence serves a purpose: stating the tool's function, elaborating on the output, and explaining how to use it. The emoji is harmless and does not detract from clarity.

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?

With no output schema, the description should convey what the agent will receive. It says 'Shows a screenshot' but does not specify whether the screenshot is returned as a file, image data, or displayed inline. It also does not mention how parameters like fullPage, elementTypes, or includeLabels affect the map, which would be useful context for a tool with 6 optional parameters. The description is adequate but incomplete.

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 coverage is 100%, with each parameter already having a description. The tool description adds minimal parameter-level meaning beyond the schema, only implying that overlays can be filtered (e.g., through elementTypes) and labeled (includeLabels). Since the schema handles parameter semantics, the baseline of 3 is appropriate.

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 'Get visual map of interactive elements with numbered overlays' and explains it shows a screenshot with number badges. This distinguishes it from siblings like get_accessibility_tree (text-based) and click_by_overlay_id (action-oriented). The reference to 'click(42)' style links it to subsequent interaction tools, making its purpose 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?

The description explicitly presents a usage pattern: 'Use "click(42)" style references', indicating this tool is a precursor to interacting via overlay IDs. While it doesn't contrast with alternatives like get_interactive_map, the context is clear for an agent to know when to invoke it—before clicking or hovering by number. The absence of explicit exclusions leaves it at a 4 rather than 5.

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