browser_find

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

Annotations already declare readOnlyHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds value beyond that by disclosing the return format (snippets with surrounding lines, each under its path from the root) and the cost trade-off versus a full snapshot.

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 tight sentence with the action and return shape front-loaded and the cost rationale trailing. Every clause contributes — nothing restates the tool name or annotations.

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?

With no output schema, the description must explain return values, and it does (matching nodes plus context lines under their paths). Minor gaps remain: no mention of match limits, truncation, or what an empty result looks like, which matter for an agent deciding whether a miss is real.

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 100%, so text/regex/session/filename are fully documented in the schema. The description only alludes to the text-vs-regex choice and adds no syntax, default, or exclusivity detail beyond it; baseline 3 applies when the schema does the heavy lifting.

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 and resource ('Search the accessibility snapshot of the current page') and names both the input forms (text or regex) and the output shape (matching snapshot nodes with surrounding context under their tree paths). This clearly differentiates it from browser_snapshot by framing it as the cheaper locate-an-element path.

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?

Gives a concrete selection rule: use this instead of capturing the whole snapshot 'when you only need to locate an element and its ref.' The alternative is described functionally rather than by sibling name, and no explicit when-not case is given, but the routing signal is unambiguous.

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