smart_snapshot

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains the filtering criteria (visible, interactive, meaningful), depth limiting, and deduplication behavior. It does not explicitly state whether the tool is read-only, but as a 'snapshot' this is implied. The inclusion of includeHidden and verbose parameters further clarifies default behavior, which the schema mirrors.

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 only two sentences and front-loads the primary action and outcome. Every piece of information is useful: what the tool returns, its key behaviors (filtering, depth limiting, deduplication), and when to use it. No fluff or repetition.

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's moderate complexity (3 optional params, no output schema), the description fully captures the purpose, filtering behavior, and usage guidance. It also points to take_snapshot as the alternative, which aids selection. The lack of output schema is compensated by the description of what the snapshot consists of ('nodes'). The tool is well understood from this alone.

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?

All three parameters are fully described in the schema (100% coverage), so the baseline is 3. The description adds semantic context by framing the tool as 'token-efficient' and 'semantic', which explains the purpose of verbose (disabled by default to save tokens) and maxDepth (limit depth to avoid huge dumps). This layer of meaning goes beyond the individual parameter comments.

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 returns a token-efficient semantic snapshot of the current page, filtering to visible/interactive/meaningful nodes with depth limiting and deduplication. This specific verb+resource+output distinguishes it from the sibling tools (snapshot_diff, screenshot_to_disk) and explicitly contrasts with take_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 second sentence 'Use this instead of take_snapshot to save context' gives an explicit, actionable usage directive. This directly tells the agent when to choose this tool over an alternative, satisfying the dimension fully.

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