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

Adds substantial side-effect disclosure beyond the spartan annotations: NOW 'sends real messages now' and SCHEDULED 'authorizes future channel delivery,' both flagged as DANGER ZONE. Also discloses the deprecated context alias, inheritance behavior, and return payload (report URL, nextRunAt, plus execution URLs and per-destination status for NOW). No contradiction — destructiveHint=false concerns data destruction, while the description transparently surfaces irreversible delivery side effects the annotation omits.

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?

Unusually long, but earns its length given 5 widget types, 3 schedule modes, nested inheritance, and a deprecation. Purpose and DANGER ZONE warnings are front-loaded, and both JSON examples are complete valid payloads rather than filler. Not a 5 because the density is overwhelming and would benefit from clearer visual hierarchy (headers or bullet separation between the schedule modes and widget types).

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 10-parameter tool with nested objects and no output schema, the description covers the input model, deprecations, return values, and required confirmation steps, then externalizes remaining depth to get_skill('reports'). The schema carries parameter detail at 100%, and the examples anchor the abstract rules. Nothing an agent needs to construct a valid call is missing.

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 coverage is 100%, so baseline is 3, but the description goes far beyond it: it dictates what belongs in reportContext ('period required when query widgets are present: prefer datePreset'), the inherit-don't-repeat rule for widget overrides, and cross-field constraints ('never send both' context/reportContext; WEEKLY requires weekday). The two complete example payloads give the agent concrete valid shapes for DIGEST and GRAPH_SNAPSHOT+TOP_FLOP that the schema alone cannot convey.

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?

Opens with a specific verb+resource+structure: 'Create a report with shared reportContext and one or more widgets plus destinations.' The schedule-mode breakdown (NOW vs UNSCHEDULED vs SCHEDULED) and widget-type enumeration make the tool's scope unambiguous against siblings like update_report, archive_report, and run_report_now.

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?

Gives explicit gates: 'Call get_skill with skillId: "reports" first' and a mandatory confirmation step before NOW/SCHEDULED modes ('ask the user to confirm before calling'). Mode selection semantics are well-specified, but it never explicitly names siblings like preview_report_widget or run_report_now as alternatives for iterating on drafts or running existing reports ad hoc.

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