files_search

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

No annotations are provided, so the description carries the full behavioral burden — and it does disclose ordering semantics (dictionary-wins on conflict, then BM25), truncation behavior (rank-order fill until budget, overflow to meta.skipped[]), and that FTS tokenisation will miss URLs and substrings. It also asserts 'read-only; no side effects, auth, or rate limits'. This exceeds the annotations bar but leaves the actual return field set and sufficiency-check behavior of check_sufficiency only lightly characterized.

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?

Purpose and default behavior are front-loaded in the first sentence, and every clause carries real information (mode switch, ordering, tokenisation caveat, filter semantics). It is however one dense wall of prose with no separation between the default-mode story, the bundle-mode story, and the filter notes, which makes it heavier to parse than it needs to be.

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 10-parameter tool with no output schema, the description supplies the missing contract: the default response shape (match_excerpt, title_highlight, total_est_tokens), the alternate shape ({bundle, meta:{included, skipped}}), defaults, and filtering semantics. An agent has enough to call it correctly and to choose between modes.

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 the baseline is 3; most description detail (tags all-match, max_tokens default 12000, format semantics) merely restates the schema. The one genuinely additive nuance is the project_id distinction — 'null searches only the KB; omit the field to span everything' — which the schema does not spell out. Marginal net gain.

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+mechanism ('Full-text (SQLite FTS5) keyword search across files') and immediately distinguishes the default mode from the include_bodies mode. It also names the sibling to fall back to (files_regex_search), so an agent can differentiate without opening any 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?

Explicit routing: use default mode for ranked snippets, use include_bodies 'instead of files_search + N×files_read when you need several related files as one context blob', and fall back to files_regex_search for URLs/hyphenated/partial substrings. Both the when and the alternatives are stated.

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