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

Annotations declare readOnlyHint=true and destructiveHint=false, yet the description describes mutating operations ("Rename, re-describe, or restyle", "style replaces the whole document"). That is a direct conflict between the stated behavior and the structured safety hints, and the annotation title "Prepare client burn" does not even match this tool. The rich detail about style replacement, override merging, and community-copy snapshots is otherwise valuable, but the contradiction dominates.

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?

Four short sentences, front-loaded with the cost signal "Free." and the operation scope, then the style-vs-overrides merge rule. Nothing is padded, though deferring validation semantics to "Validated like save_custom_preset" forces a cross-tool lookup.

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?

Given six parameters, nested objects, no output schema, and effectively unreliable annotations, the description still supplies the core behavioral model an agent needs (replace vs deep-merge, basePreset fallback, immutable community snapshots). It stops short of describing error cases for an unknown id or the response shape, but those are secondary for a preset mutation.

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 0%, so the description carries the whole burden and does so for the hardest parameters: style ("replaces the whole document"), overrides ("deep-merge onto the current style (or onto basePreset when given)"), basePreset, plus name/description via rename/re-describe. Only id is left unexplained, and the validation rules are deferred to save_custom_preset rather than spelled out.

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?

"Rename, re-describe, or restyle a saved custom preset" gives a specific set of verbs plus the resource, so the agent immediately knows this mutates an existing preset rather than creating one. It distinguishes itself implicitly from save_custom_preset by referencing it as the validation counterpart, but never names the create/delete/submit siblings outright.

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 context is implied by "a saved custom preset" (i.e., the preset must already exist) and by "Validated like save_custom_preset" for the rule set, but the description never states when to choose this over save_custom_preset, submit_custom_preset, or delete_custom_preset. There are no explicit preconditions or exclusions, so the agent must infer the branch.

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