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

With no annotations supplied, the description carries the full behavioral burden, and it does disclose several non-obvious traits: the operation is read-only, snoozed items are excluded, results are ranked best-first, and each item carries next_actions. It also explicitly reassures that 'nothing is sent', which is meaningful for an agent wary of side effects. What it omits is volume/pagination behavior and whether the scan is expensive to run.

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?

Structure is good: the scope statement leads, then short punchy sentences deliver the ranking rule, the snooze exclusion, the next_actions contract, and the no-side-effects guarantee. The opening enumeration is long, but each listed category conveys distinct coverage information rather than padding.

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 an output schema exists, the description need not describe return fields, and it usefully adds the ranking order and the presence of next_actions per item. For a multi-domain diagnostic tool this is nearly complete; the remaining gaps are item counts/limits and the single undocumented input parameter.

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 schema has one parameter (shop_id, uuid) with 0% description coverage, so the description could have compensated by explaining that the scan is scoped to a single shop. The phrase 'across the shop' hints at this scoping, but the parameter itself is never named or explained, leaving the agent to infer that shop_id selects the tenant scanned.

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 makes clear this is a composite read-only health scan across the shop, and it enumerates the specific issue categories covered (stale quotes, overdue/failed invoices, unready visits, margin-floor jobs, double bookings, due maintenance, missing setup step). That enumeration effectively distinguishes it from the narrower single-purpose siblings like agent_due or changes_list. The only weakness is that the operative verb is phrased loosely as 'a read-only look' rather than a concrete action.

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?

Usage is implied by the enumerated coverage: an agent can infer this is the 'give me everything that needs attention' entry point rather than a per-object query. However, the description never states when to prefer this over siblings such as agent_due or the approvals/changes list tools, nor does it set any exclusions or prerequisites.

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