browser_read_text

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

Annotations already provide readOnly and destructive hints, so the bar is lower. The description adds real behavioral context beyond annotations: the output is stripped of markup, is the 'cheapest way to read a page,' and long text is truncated at max_chars with a marker that signals truncation. This is useful operational detail not present in the structured metadata.

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 sentences, front-loaded with the core definition. The alternatives paragraph and the truncation behavior paragraph are each necessary and non-redundant; 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?

For a read-only tool with 3 optional parameters and an output schema, the description covers what text is returned, how to target it, when to choose another tool, and how to detect truncation. Nothing essential for correct invocation is missing.

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 33% (browser is described), but the description compensates for the other two parameters: max_chars gains truncation and marker semantics, and selector gains purpose via 'Narrow the selector when you know where the answer is.' It doesn't specify selector syntax, but it covers the missing parameters meaningfully enough.

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 precise definition: 'The visible text of an element, with the markup gone.' It names sibling tools browser_read_html and browser_snapshot and differentiates them by structure versus clickability, so an agent can distinguish this tool from close alternatives without opening schemas.

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 explicit when-to-use advice: 'Narrow the selector when you know where the answer is' and explicitly routes structure needs to browser_read_html and click needs to browser_snapshot. This is direct usage guidance with named alternatives and conditions.

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