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

The description discloses non-obvious behaviors beyond the sparse annotations: synthetic orphan:<project_id> rows for forever-paused projects, a server-derived task_retry_available flag, and exact next_tool routing rules. This gives the agent meaningful expectations about edge cases and side-channel behavior. There is no explicit contradiction with readOnlyHint=false, though the description does not promise side-effect-free behavior.

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 opening sentence front-loads the core purpose, and the remaining sentences add dense, useful detail: return fields, the synthetic-row edge case, and next_tool routing. Every sentence earns its place, and the structure is logical and scannable with no 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?

Given that an output schema exists, the description appropriately focuses on semantics rather than re-listing return types. It explains the important edge case, the server-derived flag, and how the output guides follow-up actions. For a single-parameter, data-returning tool, the description is complete enough for an agent to invoke it correctly and interpret its results.

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?

There is one required parameter, project_id, and schema description coverage is 0%. The description never explains what project_id values are valid, where the agent gets it, or any constraints/ownership semantics. It mentions <project_id> only as part of an output example, which does not compensate for the missing schema-level documentation.

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 uses a specific verb ('returns each one') and clearly identifies the resource: escalations for a project. It explicitly differentiates from project_status by noting that project_status only counts escalations while this tool returns the full rows with their fields. An agent can immediately tell what this tool does and how it differs from a sibling.

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 explains when project_status is insufficient ('only COUNTS open escalations') and describes how the returned next_tool field routes to retry_blocked_task, rearm_roadmap_item, replan_task, and resolve_escalation. It gives clear context for downstream tool selection, though it does not explicitly list exclusions such as 'do not use this when you already know the escalation ID and want to resolve it directly.'

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