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

With zero annotations, the description carries the full disclosure burden and delivers comprehensively: cost ('no LLM cost on this call'), safety ('pure DB read'), failure semantics ('Duplicate titles fail closed with candidate ids'), case-insensitive matching behavior, the by-design frozen behavior of updatedAt, and fine-grained liveness semantics for lastProgressAt including the waiting_for_subagents corner case. No structured data covers any of this, so the description is the sole source and it is remarkably thorough.

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 long, but the length is earned: the lastProgressAt versus updatedAt distinction, the waiting_no_wake detector rationale, and the frozen-progress interpretation are genuinely subtle and would cause real polling bugs if omitted. It front-loads the most decision-relevant facts (cheap, pure DB read, relevance condition) before the deep polling guidance, though a single dense paragraph is harder to scan than clearly separated sections.

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 zero annotations and no output schema, the description covers everything needed for correct invocation and polling: safety and cost profile, addressing rules, duplicate-title failure behavior, liveness semantics, sandbox step location (agent.messages[*].data.steps), and terminal states. The only gap is a full status enum, but the terminal states and the one non-terminal state that matters operationally (waiting_for_subagents) are disclosed, so an agent can poll correctly.

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?

The input schema already documents both parameters at 100% coverage, including the XOR relationship and the fail-if-not-exactly-one-match behavior, so the baseline is 3. The description adds only marginal value on top: restating 'provide exactly one' and the detail that duplicate-title failures return candidate ids. This does not meaningfully exceed what the schema provides.

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 identifies the resource ('Aurora agent surface'), the operation kind ('pure DB read'), and the returned contents ('status, plan, messages, config'), which together make the intent unambiguous and distinguish it from siblings like get_agent_trajectory and list_agents. The verb is only implied via the tool name and the word 'Returns' rather than stated as an explicit 'Gets/fetches X', which keeps it from a 5.

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?

It gives a concrete applicability condition ('Only relevant when the user is actively working with an Aurora agent') and exceptionally detailed polling usage guidance: use lastProgressAt rather than updatedAt, treat a frozen lastProgressAt during waiting_for_subagents as stalled children, confirm via child agent statuses, and poll until a terminal state. It does not explicitly name sibling alternatives for other retrieval needs, such as list_agents or get_agent_trajectory, but the context for when and how to poll is far beyond typical.

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