search_messages

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

The description discloses the semantics of the three modes and the fallback behavior when query is absent ('No query returns recent messages'). Since no annotations are provided, this is valuable behavioral context. It does not cover response format or pagination, but the core behavioral traits are covered.

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?

The description is two sentences and front-loads the core purpose. Every sentence provides useful information: the operation, the mode options, and the no-query default. No 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?

Given no output schema and no annotations, the description gives a reasonable overview but omits details like response format, how limit acts, and any sorting/pagination. The inclusion of mode semantics and no-query behavior is helpful, but more details would be needed for full completeness.

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?

The description clarifies the mode parameter ('keyword (default), semantic (by meaning), or hybrid') beyond the schema's terse 'Search mode,' and explains query behavior when omitted. However, it does not explain the limit parameter, and only half of the schema parameters have descriptions. Thus it partially compensates for the schema coverage gap.

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 clearly states the tool's function: 'Search messages across the tenant.' It identifies the resource (messages) and scope (tenant). It does not explicitly differentiate from sibling tools like get_message or list_threads, so it falls short of the highest score.

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 provides guidance on search modes: keyword, semantic, hybrid, with keyword as default. It also notes the no-query behavior, which helps the agent know when to use it without filters. However, it does not discuss when to choose this over get_message or other alternatives.

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