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

Beyond the annotations, the description discloses high-value behavior: out-of-range values are clamped to the nearest valid one and flagged via adjusted=true, room/furniture affect only the ambience image and not the price, own-image designs cap zoom at 400 and force material to vlies, and nothing is persisted ("Er wordt niets opgeslagen"). That last line resolves the apparent tension between "Wijzig" and readOnlyHint=true, so the annotations and prose reinforce each other.

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?

Very dense with essentially zero waste, and the core action plus every changeable field sits in the first sentence. It is delivered as one continuous block without breaks or a return-value sentence, so it is efficient but harder to scan than a lightly structured version would be.

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 an 8-parameter nested-schema mutation-style tool with no output schema, the description covers the action, the clamping contract, the adjusted flag and the design_id return, plus the own-image exception. What is missing is a fuller account of the return payload (what else is returned alongside design_id, and which fields can trigger adjusted) now that no output schema exists to fill that gap.

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% across 8 parameters, so the description carries the burden and does substantial work: zoom_percent 100 means full width/height, position_percent is the crop origin as a percentage from the left (x) and top (y), and room/furniture are cosmetic. Still undocumented are wall_cm, mirrored, and the material/zoom interaction for non-own-image designs, so it does not fully compensate.

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 opening clause names a specific verb ("Wijzig") plus the exact resource (a wallpaper design) and enumerates the mutable facets: wall size, zoom, crop, mirroring, material, room, furniture. It also states the outcome ("krijg een nieuw design_id"), which cleanly separates it from the sibling readers get_wallpaper_design/get_product and the initiators start_wallpaper_design/start_own_image_wallpaper_design.

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 rather than stated: an agent can infer this is for tweaking an existing design, and the own-image clause hints at the start_own_image_wallpaper_design path. However, no sibling is named as an alternative and no condition is given for when to call this versus re-running start_wallpaper_design or render_wallpaper_preview.

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