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

Annotations only declare the generic mutation profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description adds materially beyond that: charts are materialized at creation time ('Charts are drawn at once'), commentary blocks are generated 'on the user's own AI key at each refresh' (a cost/auth implication worth knowing before adding them), and it describes the return value and handoff ('Returns the dashboard and its link; the user edits, comments and refreshes it in the app'). It does not cover permissions required to create in a workspace, duplicate-title behavior, or any limits, 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?

It is front-loaded with purpose, then type selection, then the block grammar, then the optional layout/style, then the return value — a sensible order for an agent building the payload incrementally. It is dense and telegraphic ('type story: slides, each with a title and blocks'), which packs a lot into a short span but occasionally reads like a spec fragment rather than prose. Nearly every clause carries information; nothing is obviously 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?

For a tool of this complexity — a deeply nested oneOf block grammar with 7 top-level parameters, no schema descriptions and no output schema — the description is unusually complete, covering the block kinds, the query contract by reference to aggregate/chart, layout units, and what is returned. The remaining holes (mode, workspace_id, subtitle, and how slides relate to the top-level blocks array) are recoverable from the schema but are not stated here.

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%, so the description carries the full burden, and it largely meets it: it names all five block kinds and their payloads (chart, kpi, text, commentary, shape), explains the query shape by reference ('as aggregate takes it: group_by, grain, metrics, where, order_by, limit'), and clarifies the otherwise cryptic layout units ('{ x, y, w, h } in percent of a 16:9 slide; board { x, w } in 12 columns, { y, h } in rows'). Gaps remain for parameters it never mentions: mode (light/dark), workspace_id, and the top-level subtitle, any of which forces schema inspection.

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 first sentence gives a specific verb, resource and scope: 'Make a dashboard in one of the user's workspaces from queries on its datasets.' It also splits the resource into its two concrete variants (story vs board) with a one-line definition of each. It stops short of explicitly distinguishing itself from list_dashboards or refresh_dashboard, so an agent must infer that creation is this tool's job.

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 real selection guidance inside the tool: 'type story: slides, each with a title and blocks, for a narrative (a monthly review)' versus 'type board: one page of charts and KPIs with little text', so the agent can pick the right variant. It also states layout is optional ('Leave it out and blocks are laid out for you') and gives a hard constraint ('Only the workspace's own datasets can be used'), plus a pointer that editing/refreshing happens in the app. What is missing is any explicit statement of when to call this rather than a sibling (e.g. refreshing an existing dashboard).

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