find_text

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

No annotations are provided, so the description bears the full burden of behavioral disclosure. It reveals the return structure (list of objects with text/tag/match/w/h) but doesn't disclose behavioral traits: whether it's a read-only operation, whether text must be visible, matching semantics (partial vs exact), what 'tag' contains, or whether results are sorted. The provided schema includes an 'exact' boolean and 'limit', suggesting matching behavior worth explaining.

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?

The description is a single compact line with an illustrative example and return format. It's efficiently front-loaded as an example invocation. Could arguably add a short sentence of prose, but as-is it wastes no words.

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 4 parameters with 0% schema coverage, no output schema, no annotations, and a rich family of text-related sibling tools, the description is under-specified. The return-object shape is shown but fields (tag, match, w, h) are unexplained, and matching semantics (partial vs exact, case sensitivity, visible vs source text) are unclear. The example conveys the core idea but leaves too much to infer for an agent to use this reliably.

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%, and the description only illustrates usage of 'text'. Three parameters (tab, exact, limit) are entirely unexplained in both the schema and the description. The 'exact' and 'limit' parameters clearly affect behavior (exact matching, result count) but their semantics are undocumented. The description partially compensates via the example but leaves a majority of parameters without meaning.

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 shows an example call 'find_text("喜欢")' and the return format '[{text, tag, match, w, h}]', which implies this searches for text on the page. However, it never explicitly states 'Searches for text on the current page' — the purpose must be inferred from the example. It doesn't clarify what the returned fields mean or whether this searches visible/source text, nor does it distinguish from siblings like page_text, get_markdown, or wait_selector.

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?

There is no guidance on when to use this tool versus alternatives. Siblings include page_text, get_markdown, click_text, wait_selector — all text-related tools that could overlap. The description gives no when/when-not conditions, no context about what scenario this tool is best suited for, and no exclusions or alternatives.

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