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

Annotations already declare read-only/non-destructive/non-open-world, and the description adds substantial behavior on top: case-insensitive substring matching, the exact fields searched, a ranked result list, id kind-prefixes, and a hard 50-match cap with guidance to narrow the query when truncated. That is rich, decision-relevant context beyond the annotations.

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 triggering condition is front-loaded ('Use this when...'), followed by matching semantics, scope, return shape, and the truncation limit. Despite being dense, every clause carries information an agent needs; nothing is filler.

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?

No output schema exists, and the description compensates fully by describing the return shape ({id, title, url}), the id prefix scheme, ranking, and the 50-result cap. Combined with the annotations, nothing needed to call or interpret this tool correctly is missing.

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% for the single 'query' param, so the baseline is 3. The description rises above it by clarifying the matching mode (case-insensitive substring) and what the query is matched against, which is useful complement to the schema's terse 'Free-text query' note.

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 concrete verb (find by keyword) and enumerates the exact resources searched — tasks, sprints, recorded decisions, memory notes — with worked examples like 'why did we choose Neon'. This clearly separates it from the enumeration-style siblings (list_tasks, list_sprints, get_board_state) even though the tool name itself is generic.

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 a clear triggering condition (user wants to find something by keyword) plus illustrative examples spanning the resource kinds. It does not name alternatives or state when a sibling like list_tasks or get_board_state would be preferable, so routing is implied rather than explicit.

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