get_plan_dashboard

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

With no annotations, the description carries the full burden and does so well: it defines stuck work as "claims older than 2× their TTL", caps returns (up to 5 tasks, 20 events), and discloses the 5-second in-process cache with LISTEN/NOTIFY invalidation. It doesn't state that the call is read-only or note any authorization requirements, which keeps it from a 5.

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?

Two dense sentences with zero filler, front-loading the payload contents before the usage and caching notes. Every clause carries information an agent needs.

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?

With no output schema and no annotations, the description does the heavy lifting by enumerating the returned sections and cache behavior. The main remaining gap is the meaning of as_agent and whether the operation is a pure read, which would round out an otherwise complete definition.

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 0% and two parameters exist, so the description must compensate. PlanId is self-evident, but as_agent is never explained; the phrase "the caller's currently-held claims" only weakly hints that it sets caller identity. The identity semantics of as_agent are left entirely to inference.

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 resource (one plan's dashboard) and enumerates exactly what the snapshot contains: per-status counts, per-phase counts, next-claimable tasks, caller's claims, stuck work, and recent events. This aggregation role distinguishes it from focused siblings like get_stuck_work, get_event_log, and get_my_active_work without the agent needing to open any schema.

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?

"This is the single call an orchestrator makes every iteration to decide what to do next" gives a clear, actionable when-to-use condition tied to a concrete workflow. It stops short of naming alternatives to avoid (e.g., use get_stuck_work for a narrower stuck-work view), so it is a strong 4 rather than a 5.

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