Apply a style variation

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

Whereas the annotations only signal readOnlyHint=false and destructiveHint=true, the description discloses exactly what is destructive — a full variation 'replaces the user's global-styles customisations' — and reveals the safety valve: state is preserved as a global-styles revision and the endpoint to undo is given. The dry-run/diff behavior without confirm_token is also explicitly spelled out, which is substantial context beyond the structured fields.

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 four sentences are front-loaded with the core action and then cover dry-run behavior, mutation semantics, and undo path — each earns its place and the ordering is logical. It is somewhat dense with parenthetical asides, but nothing is wasted or repetitive relative to the schema.

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 destructive mutating tool with no output schema, the description covers the full call lifecycle: preview and diff output, commit via confirm_token, replace-vs-merge behavior, and precisely how to undo via revisions. Given the tool's complexity and its destinations, nothing an agent needs to invoke it correctly or safely 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 description coverage is 100%, and each parameter is already well documented in the schema (enums, defaults, source from list_style_variations, confirm-token semantics). The description does usefully tie kind and mode to real side effects (full replaces vs partial merges), but that relationship mostly duplicates the schema's auto-mode explanation, so it does not add much beyond the documented baseline.

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 opens with a specific verb plus resource ('apply one of the active theme's style variations to the site's global styles') and grounds it in a familiar UI action ('what choosing it in Site Editor → Styles does'), so an agent immediately understands the purpose. It is also easy to distinguish from siblings like get_global_styles, update_global_styles, diff_global_styles, and list_style_variations because it names the precise action and the input source.

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 gives clear, actionable usage conditions: omit confirm_token for a dry-run preview and include it to commit; it also explains how the tool behaves depending on kind (full replaces, partial merges). It does not explicitly name when-not-to-use alternatives such as update_global_styles or diff_global_styles, but the Site Editor analogy and the dry-run/confirm contract give a strong practical usage frame.

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