browser_snapshot

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

Beyond the readOnlyHint and openWorldHint annotations, the description discloses non-obvious runtime behavior: it 'waits briefly for data the page is still fetching', long texts are truncated with a line at the top reporting how much, and full_text disables that truncation. Truncation and implicit waiting are exactly the traits an agent would otherwise misread as missing data or a stale 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?

Six short sentences, each carrying distinct information: output format, positioning versus screenshots, waiting behavior, scoping advice, and truncation handling. The most important framing, what the tool returns, is front-loaded, and there is no filler.

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?

There is no output schema, so the description carries the burden of explaining returns, and it does: an indented accessibility tree with [ref=N] markers plus a truncation notice. Combined with the scoping and waiting notes, an agent has everything needed to call this correctly on both small and large pages.

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 100%, so the schema already explains ref, text, limit, selector, and full_text, making 3 the baseline. The description adds only light context, chiefly that ref and selector are for scoping large pages and that full_text prints every word, which mostly restates the schema's 'Texts, names and values uncut'.

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 opens with a concrete verb-and-resource statement: 'The page as an indented accessibility tree'. It names the [ref=N] markers that actionable elements carry, which tells the agent exactly what the output enables, and it distinguishes the tool from browser_screenshot by calling itself 'the main way to read a page'.

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 clear usage conditions: use this as the primary page-reading tool, prefer it over a screenshot because it is 'cheaper and more exact', and scope it with ref or selector on large pages. It stops short of stating exclusions, such as when a visual check or a screenshot is actually required, so it is not a full when/when-not/alternative treatment.

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