Create Card Builder style preset

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

Annotations already declare readOnlyHint=false and idempotentHint=false, so the write/non-idempotent profile is partially covered. The description goes beyond that by explaining the mechanism ('assigns a new id server-side... every create path generates a fresh uuid4') and the practical consequence ('repeating this call creates a second, distinct preset rather than updating the first'), which tells the agent retry semantics. It does not cover permissions or whether the created preset is immediately persisted/visible, so it stops short of 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?

Front-loads the action, then uses labeled 'Use when' / 'Not for' / 'Returns' structure that is easy to scan. The parenthetical aside about upstream storage.py is slightly more detail than needed, but it is short and it justifies the non-idempotency claim rather than 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 4-param mutation tool with full schema coverage, an output schema, and annotations covering the safety profile, the description supplies everything the agent additionally needs: the action, the routing alternative, non-idempotency consequences, and the existence of a new generated id. Nothing material 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%, so all four parameters (name, data, description, extends_preset_id) are already documented in the schema, including the inheritance semantics of extends_preset_id — baseline is 3. The description adds only loose context ('a set of style properties, e.g. a card theme') and no syntax or format detail beyond the schema.

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?

States a specific verb and resource ('Create a new reusable Card Builder style preset') and immediately distinguishes itself from the sibling it is not ('Not for: changing an existing preset — use card_builder_update_style_preset'). An agent can pick between the two create/update tools without opening either schema.

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?

Gives an explicit 'Use when' condition (packaging reusable style properties to apply across multiple cards) and an explicit 'Not for' exclusion that names the alternative tool. This is the full when/when-not/alternative pattern; nothing is left to inference.

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