Search the project

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

Annotations only declare readOnlyHint and openWorldHint; the description adds substantial context beyond that: the allowed file extensions, the fact that locally created files are invisible until push_changes, case-insensitivity, single-line matching, the 4,000-character line window, the 10-second regex timeout, and the Overleaf-first ordering.

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?

Information is front-loaded: purpose and return format come first, then the routing advice, then the constraints. It is dense and somewhat run-on, but nearly every clause carries a distinct constraint, so there is little waste.

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 search tool with no output schema, the description covers the return format, filtering limits, file-scope restrictions, error behavior and staleness caveats. An agent has everything needed to call it correctly and interpret the result.

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 100%, so all four parameters are already documented, making 3 the baseline. The description does add a little meaning (maximumMatches counts matching lines taken in path order, and both modes are case-insensitive), but most of the extra detail is behavioral rather than parameter-specific.

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 (search) and resource (the project's text sources), specifies both modes (literal string or regex), and gives the exact return shape (path:line: text). It also distinguishes itself from read_file, read_section and list_files by naming when each is appropriate.

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 frames the use case ('when you do not know which file holds it') and routes the agent to the right siblings once the location is known ('use read_file or read_section, and use list_files to find a file by name'). Both the when and the alternative are stated.

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