search_mail

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

With no annotations present, the description carries the full burden and does disclose non-obvious behavior: a hard cap of 100 metadata records and the deliberate exclusion of local filesystem paths. It stops short of stating read-only semantics, pagination/offset behavior, or what happens when results exceed the cap.

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 short sentences, front-loaded with purpose, then syntax examples, then return behavior. The examples earn their space because the schema gives no query documentation, though the return sentence partly duplicates what the output schema already conveys.

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 explanation is optional, yet the description usefully adds the 100-record cap and path exclusion. The remaining gap is the 0%-covered sort/limit/descending parameters, which an agent must infer or default blindly.

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%, so the description must compensate and largely does not. It illustrates the 'query' parameter with mu syntax examples and hints at a result cap, but says nothing about sort, limit (default 20 vs the stated 100 ceiling), or descending, leaving three of four parameters semantically undefined.

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 states a specific verb+resource: 'Search the local mu-indexed mailbox', including the query dialect used. It implicitly contrasts with read_mail by being a search rather than a fetch, but never names the sibling explicitly.

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?

Usage is implied via three concrete example queries, which shows the agent how to form a query. However, there is no statement of when to choose search_mail versus read_mail, nor any prerequisite (e.g. that a mu index must already exist) or exclusion.

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