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

Goes far beyond the annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=false): it explains override-vs-inheritance semantics, that built-in 'default:*' palettes are duplicated into a Riddle-owned copy, that newPaletteName always operates on a copy, that modifiedAt/modifiedBy are NOT bumped so polling won't detect it, and that the real detector is riddle_get's context.modified.hasChanges with caveats around context.preset.drifted and parentId. It also names the access precondition origin.writableByThisKey.

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 core action and the scope constraint before the operational caveats, and almost every sentence carries unique information (override semantics, publish requirement, detector, access). It is dense and slightly run-on, with a mild bit of throat-clearing ('Two things to know'), so not maximally tight, but nothing is 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 non-idempotent mutation with 5 params (nested values object) and no output schema, the description supplies everything an agent needs: scope, path source, copy/override behavior, propagation timing, detection signal, and access precondition. No material gap remains.

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% (baseline 3), and the description adds genuine meaning: newPaletteName always works on a copy leaving the original untouched, paletteUUID accepts built-in ids like 'default:timeless' to start from that palette, and omitting paletteUUID targets the currently selected palette. This complements rather than merely repeats 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 precise verb+resource+scope: 'Changes the palette (colors, fonts, button styles, background) of ONE Riddle, as a path => value map'. It explicitly names the sibling/related tool for paths (palette_get) and the reference resource, so it is distinguishable from palette_get without opening a 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?

Clearly implies when to use it (restyle a single Riddle's palette via path=>value map), routes the agent to palette_get and riddle://reference/palette/fields for valid paths, and flags that the change only reaches the live embed after riddle_publish. It stops short of stating explicit exclusions (e.g. when to prefer palette_get or project-level preset tools), so it is strong context rather than full when/when-not guidance.

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