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

Annotations only say destructiveHint=true; the description explains exactly what is destroyed — list fields (steps, products, tags, categories, occasions) are replaced whole rather than merged. It also discloses that look photos are preserved and that certain payloads are refused, which is meaningful behavior beyond the annotation flag.

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?

It is front-loaded with the partial-update rule and every sentence carries a constraint that is not in the schema, so little is wasted. The trailing sentence ("To unlink every step, send products too") is compressed to the point of ambiguity and could be stated more plainly.

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 14-parameter mutation tool with a nested steps array, the description covers the highest-risk semantics (whole-list replacement, photo lock, ref coupling) and an output schema exists, so return values need not be explained. It does not mention recovering the id via search_my_looks, which the schema handles, leaving only a minor 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 coverage is 100%, so the baseline is 3, but the description adds cross-field meaning the schema cannot express: refs are 0-based indexes into the products array and must accompany every step sent, [] for none, and products must be sent together with steps to keep refs valid. The remaining gap is that the interplay is dense and the final sentence about unlinking is hard to parse.

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?

"Change a saved look" is a specific verb plus resource, and the description immediately qualifies it as a partial update ("Only the fields you send change"). It does not name the sibling it differs from (save_my_look, get_my_look, delete_my_look), so the agent must infer the boundary from the name alone.

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?

It gives real when/when-not guidance: steps cannot be changed while any step carries a photoUrl, and in that case the user edits in the BeautySpark app. It also states the productRefs/shadeRefs obligation per step and the refusal condition, though it never routes to an alternative tool for the blocked case.

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