page_look

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

With no annotations, the description carries full burden. It discloses that the overlay is removed after capture, refs from prior snapshots/finds are invalidated, only truly visible elements get badges (covered/clipped are skipped and counted), the image is 1:1 with CSS px, and filters/inclusion options alter marking. These are valuable beyond the schema.

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 dense but efficient. It front-loads the core purpose, then covers usage, visibility caveat, pixel mapping, optional filters, and invalidation—each sentence adds unique value without repetition. No filler or redundant phrasing.

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 complex tool with 7 optional parameters and no output schema, the description covers the essential behaviors: how to obtain refs, the impact of filtering, invalidation of prior refs, and pixel accuracy. It omits explicit mention of whether the screenshot is viewport-only or full-page, but the 'way you'd click it' phrasing and pixel mapping imply viewport. Overall, adequate for safe invocation.

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 86% (six of seven params described). The description adds extra meaning: text/role/selector filters mimic page_find, includeNonInteractive is ignored when selector is given, limit is in ref order, and fullRes preserves native pixels. This goes beyond the schema's straightforward descriptions.

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: it captures a screenshot with numbered badges on interactive elements (Set-of-Mark) and a legend mapping badge N to ref eN. This clearly differentiates it from siblings like page_screenshot (plain screenshot), page_find (locating elements), and page_snapshot (DOM snapshot) by emphasizing the clickable-ref mapping.

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 explicitly tells the agent how to use it: read the picture, pick a number, then call page_click with the ref. It also contrasts with page_click_at for raw CSS-pixel clicks and references page_find for filtering. It does not list explicit when-not-to-use cases, but the usage flow is clear and actionable.

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