browser_read_text

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

With no annotations, the description carries the behavioral burden, and it delivers: it discloses that only visible text is returned, that long text is truncated at max_chars (6000 default), and that the return value marks the cut so the agent can detect truncation by the marker's absence. It doesn't cover edge cases like missing selectors, but the core read behavior is transparent.

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?

Four compact sentences with no filler. The most important outcome is first, followed by usage guidance, then a precise truncation caveat. Every sentence earns its place and the whole is scannable.

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 an output schema exists (so return formatting is covered elsewhere) and only two optional parameters, the description supplies enough to invoke correctly: what it returns, how to narrow it, and how to detect truncation. A minor gap is not stating behavior for multiple matching elements or a missing selector, but the core workflow is complete.

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 explains selector as the element to narrow and max_chars as the truncation limit with a default of 6000 and a marker behavior. This adds real semantic meaning beyond the raw schema, though it doesn't explicitly state that selector uses CSS syntax.

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 starts with a crisp definition—'The visible text of an element, with the markup gone'—which names the resource (element text) and operation (read). It also distinguishes from siblings: browser_read_html for structure and browser_snapshot for clicking, so an agent can tell them apart immediately.

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?

Explicitly instructs when to use this tool: 'Narrow the selector when you know where the answer is' and when to prefer alternatives: 'use browser_read_html instead when the structure matters, or browser_snapshot when you need something to click.' It also frames it as 'the cheapest way to read a page,' giving a cost-based decision signal.

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