Collect while scrolling

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

With no annotations available, the description carries the burden of behavioral disclosure. It reveals the hard ceiling on steps, optional nested scroll targeting, early-stop conditions, and stoppedReason in results. This goes beyond a tautology, though it does not detail tab defaults or the exact result structure.

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?

A single sentence that front-loads the core behavior and packs in the bounded-step ceiling, per-step extraction, nested container option, and early-stop condition. Every clause adds value and there is no wasted wording.

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?

The tool is complex with 12 parameters, nested objects, and no output schema. The description explains the main flow but omits the full result contract beyond stoppedReason, noNewItemsForSteps semantics, and guidance on dedupeBy or maxItems. It is adequate but not complete for fully correct 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 only 58%, and the description adds useful relational meaning for steps, until, extract, and scroll (e.g., 'hard ceiling when until is set'). However, many parameters such as dedupeBy, maxItems, after, tabId, delayMs, documentId, and sessionTabId are left to the schema or remain undocumented by the description.

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 uses a specific composite verb phrase: scroll bounded steps, extract selected elements each step, optionally target a nested scroll container, and stop early via until conditions. This makes the tool's purpose clear and distinguishes it from simpler siblings like scroll or extract_elements.

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 clearly implies the use case: repeatedly scrolling a page while collecting matching elements across steps, with bounded steps and optional early termination. It does not explicitly name alternatives or exclusion criteria, but the context is clear enough for an agent to decide when this composite tool fits.

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