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

The annotations already flag destructiveHint=true and idempotentHint=true. The description adds real behavioral information on top of that: the audience is re-checked against the restored version, a version built on data its owner does not own stays private, and the reply reports this. It does not say whether the superseded live version is kept and still recoverable, which is the main remaining gap for a destructive operation.

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 sentences, with the core action and the permission scope stated up front, and the audience re-check appended as secondary detail. Dense but no sentence is wasted; the phrasing is slightly convoluted in the first clause.

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 two-parameter destructive tool with rich annotations and no output schema, the description covers permissions, version selection, and the access re-check side effect. It falls short only on what happens to the current live version and whether the rollback can itself be undone.

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% and the schema already documents both parameters, including the 'previous' constant. The description restates the number-or-'previous' semantics rather than adding format, edge-case, or validation detail beyond what the schema already says.

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 states a specific verb and resource: making an earlier version of a dashboard the live one. It is clear what the tool does, but among siblings such as dashboard_promote, dashboard_promote_version, and dashboard_versions it never draws the line that tells an agent which one to pick.

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 a usable precondition (you own the dashboard or it is shared with you for editing) and explains the version argument, which implies when to use the tool. But it never states when this should be used instead of dashboard_promote_version or when it should not be used at all.

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