read_url

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

Adds real behavioral context beyond annotations: 'Blocked pages return just the status line' tells the agent how failure looks, and the mode/query switches are disclosed. However, annotations say readOnlyHint=false and the description never explains that loading a URL mutates browser state (current page/tab), nor does it cover caching (use_memory), retry behavior, or wait semantics for a 12-parameter open-world tool.

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?

Front-loaded with the primary purpose and the sibling it replaces, then parameter notes in descending importance. It is dense and telegraphic but nearly every clause carries information; only the fragment style slightly hurts readability.

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?

An output schema exists, so return values needn't be described. But for a 12-parameter, open-world fetch tool with helper siblings, omitting truncation (max_chars/offset), main_only, and wait/settle semantics leaves genuine gaps an agent will hit on long or JS-heavy pages.

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 carries the full burden, yet it explains only 3 of 12 parameters (mode, query, with_refs). Nine parameters — offset, max_chars, main_only, links, retries, settle_ms, use_memory, wait_until — are completely undocumented anywhere, leaving the agent to guess at truncation, pagination, and timing behavior.

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?

States a specific verb+resource ('Open a URL and read it') and immediately scopes it against the sibling pipeline ('use instead of navigate + get_markdown'). An agent can tell exactly what this does and why it exists alongside navigate/get_markdown.

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 names the alternative it replaces (navigate + get_markdown) and gives conditional usage for query ('returns only the matching snippets … instead of the whole page') and with_refs. It stops short of stating when NOT to use it (e.g., when you only need find_in_page on an already-loaded page, or when snapshot is the right call).

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