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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restatement. The description earns credit by adding behavior not in the annotations: the corpus is a curated set of ready-to-send messages, and results are capped at 8 with ids and page links, which tells the agent about result volume and follow-up affordances.

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 purpose and its examples are front-loaded, and the second sentence delivers the two operational facts (optional filter, result cap). The example list is slightly long but each example illustrates a distinct kind of query, so it largely earns its space.

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?

With only two parameters, no output schema and full annotation coverage, the description supplies what is otherwise missing: result count, what each match contains, and how to phrase the query. The only gap is behavior on zero matches or how to then retrieve a full message, which is minor for a search tool with an explicit result cap.

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, but the description adds real value by showing the intended shape of the query parameter through four concrete situation phrases, which is far more instructive than the schema's "The situation, in plain words." It also clarifies that business is a narrowing filter rather than a required constraint.

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 gives a specific verb and resource ("Search ... ready-to-send customer messages ... by situation") and enumerates concrete query situations, so an agent knows exactly what this retrieves. It stops short of naming the siblings find_guides or find_owner_stories to state how it differs, though the resource name itself ('messages') already separates it from guides and owner stories.

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 rather than stated: the situational examples make clear this is for natural-language situation search, and "optionally narrow to one kind of business" covers the optional filter. There is no explicit exclusion or routing advice — nothing says to use get_message to fetch a full message by id after finding it, nor when find_guides would be the better choice.

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