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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds meaningful behavioral context beyond this: ordering, filter precedence, the default exclusion of PENDING escalations, and the detailed structure of each returned escalation (rule, identity labels, score/badge snapshot, triggering conditions, delivery channels). This gives the agent a solid understanding of what the tool returns and how it behaves, though it does not mention pagination or the includeDeletedRules default (which is in the 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?

The description is only three sentences, each serving a clear purpose: state the primary function and ordering, explain filter behavior and defaults, and list the return payload fields plus the sibling alternative. Information is front-loaded (the core action appears first) and there is zero fluff or redundancy. Every sentence earns its place.

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?

For a list tool with six optional parameters and no output schema, this description covers the essential behavior: what it lists, the order, the filter semantics, default filtering, and the shape of each returned item. It also points to escalation_summary for aggregate counts. Minor omissions like explicit pagination handling (though limit is in the schema) and a pointer to get_escalation for single records prevent a 5, but given the schema and annotations already supply parameter details and read-only behavior, the description is complete enough for correct invocation.

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?

While the schema already documents all 6 parameters with descriptions (100% coverage), the description adds valuable parameter-interaction semantics by explaining that filters are alternatives applied in a specific order and describing the default when no filters are given. This goes beyond the individual parameter descriptions and helps the agent reason about combined usage. No parameter descriptions are repeated, so the added value is genuine.

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 action ('List'), the resource ('the current customer's escalations'), and the ordering ('newest first'). It also distinguishes the tool from siblings like escalation_summary ('Use escalation_summary for counts by status') and implicitly from get_escalation and list_escalation_rules. An agent can immediately understand what this tool does and how it differs from related tools.

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 explicitly directs users to escalation_summary for counts by status, providing a clear alternative for a different need. It also explains the filter semantics ('Filters are alternatives applied in this order') and default behavior, giving context for when to use this tool. It does not explicitly mention get_escalation for single-record retrieval, but the distinction is implied by 'list' versus 'get', so this is a minor omission rather than a misleading one.

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