Search the NAS

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

Annotations already mark this as a safe, idempotent read, so the description focuses on what annotations cannot convey: 'total is always null', pagination via next_offset, dedup by share_path if the index changes mid-pagination, and a latency warning that a single search can take seconds to minutes so back-to-back calls should be avoided. The error-code taxonomy adds operational context an agent could not infer from structured fields.

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?

Front-loads purpose, then result shape, then pagination, then performance, then troubleshooting — each sentence carries distinct operational information with no filler. The parenthesized field list and exit-code map are compact rather than verbose.

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?

There is no output schema, and the description compensates by enumerating the returned fields and explaining that total is intentionally null. For a 4-parameter, long-running, paginated search tool, the pagination, dedup, latency, and error handling coverage leaves no significant gap for correct invocation.

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 the baseline is 3. The description goes beyond the schema by explaining the offset/next_offset relationship and clarifying that max_results pages automatically to collect several results, which the schema only states tersely as 'limit is then ignored'.

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 NAS by file name and document text') and immediately scopes the result surface. The only sibling is 'status', which is plainly unrelated, so an agent can distinguish the two without opening either 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?

Gives explicit routing rules: use next_offset as offset for the next page, or max_results to collect several pages at once. It also adds fallback advice when nothing is found (shorter query, full-width/half-width, English/Japanese spellings) and per-exit-code remediation, including 'retry once' for exit 4 and 'ask the user to start it' for exit 8.

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