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

Annotations already cover read-only/idempotent/non-destructive, so the description is free to add the non-obvious semantics: 'Do not sum company financial values' warns that cross-page aggregation is invalid, and 'describe partial rows as the highest-ranked returned accounts' discloses that a paginated slice is top-N, not a complete risk set. Those are real behavioral traits an agent would otherwise get wrong; return format and pagination mechanics are left to the output schema.

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?

Four tight sentences: output modes first, then ranking/pagination caveat, then a costly-mistake warning, then the sibling route. Only the opening clause is soft marketing framing that could be replaced by a direct verb.

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 values needn't be described, and the description does cover mode selection and two correctness traps. Given 21 optional parameters with near-zero schema descriptions, however, an agent still has to guess how to shape a real query, which is the dominant gap for a tool of this complexity.

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?

With 21 parameters and only 14% schema description coverage, the description must carry the load and it explains almost nothing — no mention of columns, group_by/group_sort_by interplay, health_label, date ranges, has_open_deals, or detail mode. The only hints ('count groups', 'Do not sum financial values') are echoes of schema text, leaving most parameter meanings undocumented anywhere.

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 the resource (companies / Customer Health) and the three output modes it can produce: exact Customer Health KPIs, paginated company records, and count groups. The opening sentence ('Identify customers needing attention, quiet accounts...') is more use-case framing than a verb, but the second sentence pins down what is actually returned, and it explicitly distinguishes itself from get_deals.

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 usage context (risk/health review, quiet accounts, health changes) and names one explicit alternative: 'Use get_deals for open expansion opportunities.' It stops short of stating when *not* to call it or covering the other siblings, but the routing hint plus stated scenarios give an agent enough to choose correctly.

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