Review every engagement at once, worst first

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

With no annotations provided, the description carries the full behavioral burden. It discloses that the tool reads all stored engagements, sorts them by risk, computes progress, overdue/blocked actions, live high risks, staleness, and critical health findings, and returns a verdict with named items for stalled engagements. The read-only nature is strongly implied by 'review' and 'roll into one table,' and no mutation behavior is hinted at.

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 front-loaded with the core function and then presents the output columns and verdict logic in a logical, structured way. It is slightly longer due to full bilingual duplication, but both the Japanese and English versions are parallel and fill the description with relevant information rather than generic 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?

In the absence of an output schema, the description compensates well by specifying the table contents, the verdict categories, and the fact that stalled engagements include specific named items. All four parameters are documented in the schema with defaults and constraints. Edge cases and error behavior are not covered, but for a read-only review tool this is sufficient.

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 100%, with every parameter already documented with defaults, types, and ranges. The description reinforces the concept of staleness and the worst-first ordering, but it does not add meaningful depth beyond what the schema already provides for asOf, lang, staleDays, or includeArchived.

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 names a specific verb and resource ('roll every stored engagement into one table, worst first') and enumerates the exact per-engagement metrics it aggregates. It also positions itself as the only tool for cross-engagement review, clearly distinguishing it from single-engagement siblings like check_engagement_health or list_engagements.

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?

The description clearly signals the intended use case — reviewing multiple engagements at once, worst first — and explicitly claims to be the only tool for this purpose. It does not name sibling alternatives or state when not to use it, but the scope is unambiguous enough for an agent to route to it correctly.

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