find_text

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

No annotations are supplied, so the description carries the full burden. It discloses the return format (offsets + snippet), the skip of tables, and the direct coupling to propose_replace_text. However, it does not mention regex behavior, case-sensitivity defaults, doc_hash validation semantics, or scope_element_id scoping, which are meaningful behavioral traits for a search tool with zero annotation coverage.

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?

Three tight sentences with zero filler. The core purpose is front-loaded, the return format follows, and the key limitation is last. Every sentence earns its place.

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-value details are covered by structured data, and the description adds workflow context plus the tables caveat. But with 6 parameters, no annotations, and near-zero schema coverage, the description leaves doc_hash and scope_element_id behavior unexplained. Completeness is adequate for a simple search but thin for the parameter surface.

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% across 6 parameters, and the description compensates little: it explains the output semantics and mentions 'propose_replace_text' but never describes the input parameters. is_regex and case_sensitive are only implied by their names; doc_hash and scope_element_id are completely unexplained. With zero coverage, the description should have done far more to clarify parameter 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?

The description opens with a specific verb+resource ('Find exact occurrences of text inside document blocks'), then sharpens the scope with 'inside document blocks' and 'Tables are skipped (cell-level search not supported)'. This clearly distinguishes it from siblings like read_document and get_outline, so an agent can tell what it targets without opening the schema.

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 concrete workflow guidance: 'feed these offsets directly into propose_replace_text', which tells the agent how the output plugs into a downstream tool. It also flags the tables limitation. It does not explicitly state when-not-to-use versus read_document or propose_insert_block, but the workflow hint provides clear context for the intended search-then-replace flow.

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