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

Annotations already declare destructiveHint=true and readOnlyHint=false, so the bar is lower, but the description still adds real behavioral detail: 'Deleting a dashboard keeps its widgets' (what survives a destructive action), 'filters replaces the whole object' (replacement vs merge semantics), and the default layout behavior for tiles without layout options. It stops short of permissions, reversibility, or response information, which keeps it off 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?

The opening clause is front-loaded with the action set, and every subsequent clause carries payload detail rather than filler. The drawback is that the per-action body specs are packed into a single dense parenthetical block, which is harder to scan than a short bulleted structure would be.

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?

This tool multiplexes seven actions with nested object bodies and has no output schema, so it needs to explain nearly everything itself. It covers most action bodies well, but leaves remove_tile undocumented, does not map id/tile_id to specific actions, and says nothing about what a successful call returns or how the replace-all filters semantics affect existing tile state.

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?

With schema coverage at only 25% and four parameters, the description does most of the work: it spells out the body shape for create, update, add_tile, update_tile and reorder_tiles, including nested field names for filters, variables, layout_options and overrides. Gaps remain: id vs tile_id usage per action is never explained, and the remove_tile body is not described at all.

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 concrete verbs and a concrete resource: 'Create, update or delete a dashboard, and add, lay out, reorder or remove its tiles.' That is precise enough to distinguish it from get_dashboards (read path) and from edit_widgets/edit_saved_views, which are the nearest siblings.

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?

The description implies usage through the action list and body shapes, so an agent can infer which action to pick for a given intent. But it never states when to use this tool instead of get_dashboards or edit_widgets, and it does not say that tile widget_ids must already exist (presumably created via edit_widgets), or which parameters are needed for each action.

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