swap_card_project_variation

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

Annotations declare openWorldHint=true and destructiveHint=false, so the agent knows this is a non-destructive remote mutation; the description does not contradict that. It adds useful partial-update semantics ('one or more customizations', map-based), implying unlisted customizations are left untouched, but says nothing about permissions, validation failures for mismatched variation UUIDs, or what the call returns.

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 tight sentences: the action and scope come first, the argument shape second. No filler, no repetition of the tool name, and the examples are parenthetical rather than intrusive.

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, no-output-schema mutation tool, the definition covers the action, the affected resource, and the argument encoding, which is most of what an agent needs. It stops short of describing the outcome of the swap or the failure mode when a variation UUID is invalid, which would be valuable given there is no output schema.

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 both parameters are documented in the schema, including the {customization_uuid: new_variation_uuid} map shape. The description's 'Pass a map of customization UUID → new variation UUID' restates the schema rather than adding format details, so the baseline 3 is appropriate.

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 gives a specific verb ('swap') and resource ('customizations on a project'), plus concrete examples (paper type, color, size) that make the effect on the card project unambiguous. It is clear enough to distinguish from generic writers like update_website_customization or update_current_theme, though it never names a sibling to route the agent away from.

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?

Usage is implied by the description — you use this when you already have a card project and want to change existing customization selections. There is no explicit when/when-not guidance, no stated prerequisites (e.g. that variations must belong to the same customization), and no named alternative for single-item edits.

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