revise_prop

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

With no annotations, the description carries the behavioral burden and does well: it discloses the global blast radius (every instance using the asset), that geometry/material locks remain independent, and the retention behavior when apply_design is omitted. It stops short of stating permissions, reversibility, or undo semantics for a broad mutation.

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, then layers scope, alternative, and parameter guidance in short sentences with no filler. Slightly fragmented across four line-items, but every 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?

No annotations and no output schema mean the description should fully cover behavior; it covers scope, locks, and the design/omit semantics, but says nothing about the quality or parameters inputs or what happens on failure. Adequate for intent selection but incomplete for a 5-param 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 coverage is 0% across 5 parameters, so the description must compensate. It explains apply_design (uses the asset's saved design_asset brief including construction details, omit to retain original) and apply_project_style implicitly, but leaves 'quality' and 'parameters' entirely unexplained, so only partial compensation.

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+resource ('Change shared recipe dimensions or apply the current project style') and immediately scopes it as affecting the shared recipe rather than an instance. It explicitly contrasts with the sibling edit_scene, so the agent can differentiate without reading schemas.

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 alternative and the condition that selects it ('This changes every instance using this asset. For one instance use edit_scene instead'), plus guidance on omitting apply_design to retain the original design. When-to-use and when-to-use-something-else are both covered.

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