apply_decoration

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

With no annotations, the description carries full disclosure weight — and it delivers. It transparently discloses the inline 3D stage side effect, automatic decimation of oversize meshes, and host-dependent fallback behavior ('in hosts that render MCP Apps panels... attaches a browser stage link for hosts that don't'). It falls short of a 5 only because it omits error/failure behavior and what happens when the named decoration doesn't exist.

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-loaded with a punchy one-liner, then the core value prop, then params, then rich behavioral notes — a logical downward-spiral of detail. The only waste is 'This is the magic tool —' which is marketing fluff that doesn't add functional info. The param docs use reST format with helpful types but add a bit of noise. Otherwise, every other sentence earns its place.

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 the tool's complexity (5 params, side-effectful 3D stage, no output schema), the description covers all essential dimensions: purpose, params, return value ('Dict with decorated model path and settings used'), and side effects. The gap is that it doesn't discuss error conditions, performance expectations for large models, or whether the tool mutates the original file. It's thorough, but a few edge-case behaviors would make it complete.

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?

Param semantics are excellent. The description's docstring block provides meaning for all 5 params, even though schema coverage is 0%. It explains name is a 'slug', model_path accepts 'STL or OBJ' formats, material is an 'Override (empty = use proven or detect from printer)', face has values 'auto, top, bottom, etc.', and printer_id is 'for material detection'. This exactly compensates for the empty schema descriptions.

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 line 'Apply a saved decoration to a new model — proven settings, one call' is a specific verb+resource+scope statement. It's further clarified with 'Loads a previously saved decoration and applies it to the target model using the exact settings that worked before,' clearly distinguishing this from sibling decoration tools like decorate_surface by emphasizing the 'replay a proven recipe' angle.

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?

The description implies when to use: when you have a saved, proven decoration to replay ('proven settings, one call', 'decorations that took many iterations to perfect can be replayed'). However, it never explicitly names an alternative (e.g., 'use decorate_surface for new decorations') or provides when-NOT-to-use guidance. The usage context is clear but implicit rather than explicit, and no exclusions are given.

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