Browser Snapshot

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

With no annotations, the description carries the full behavioral burden, and it does well: it discloses an internal cached-snapshot behavior ('returns a short unchanged notice instead of re-sending the tree'), the stability of refs across snapshots, and the exact effect of force ('always re-render') and deep ('include child frames'). It omits side-effect details, but as a read-style capture tool the disclosed behaviors are the ones that matter for invocation.

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?

Three sentences, zero waste. Purpose is front-loaded first, followed by the ref mechanism, the caching behavior, and parameter flags. Every sentence earns its place and the token-savings note is a high-value addition rather than 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?

Given the tool has an output schema (so return shape need not be spelled out) and moderate complexity, the description is nearly complete: it covers output behavior, refs, caching, and both behavioral flags. The only real gap is the omitted tab and session parameter semantics, which is minor since both have schema defaults and are common suite-wide patterns.

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%, so the description must compensate. It explicitly explains force=true and deep=true, covering half the parameters with real semantics. However, tab and session are left completely unexplained, and the schema provides no descriptions either, leaving an agent to infer their meaning from sibling-tool conventions.

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 specific verb+resource: 'Capture the page as a compact, ref-annotated accessibility snapshot.' It further distinguishes itself from extraction siblings (browser_extract_text/html, browser_screenshot) by explaining the ref mechanism ('Elements get stable refs (e.g. [ref=e12]) that interaction tools accept'). An agent can clearly tell this is an accessibility-tree capture, not a text, HTML, or visual snapshot.

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 implies clear usage context: use this when you need stable refs for interaction tools, and it advertises a major efficiency benefit (token savings via the 'unchanged' notice). It does not explicitly name alternatives or state when not to use it, but the benefit framing alone gives an agent enough signal to select it over screenshot/extract siblings.

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