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

Beyond the annotations (readOnly=false, destructive=false, idempotent=false), the description discloses cost and side-effect boundaries ('No media generation, credit charge or library change'), an optimistic-concurrency requirement ('requires the current brief revision'), the return shape ('Returns a new brief and quote'), and a required workflow ordering ('Read the returned recipe_key before the next edit'). That is exactly the extra context annotations cannot carry.

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?

The mutation verb and its append/replace modes lead, followed by scope, prerequisites, side-effect exclusions, return value and follow-up action — each sentence adds a distinct fact with no filler.

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 mutation tool with no output schema, the description covers preconditions, side effects, return summary and next-step workflow. What it lacks is any detail on the returned 'quote' or the structure of the new brief, and the relationship of shot_index to photo format is only loosely implied.

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 63%, with brief_id, shot_index and expected_brief_revision undocumented in the schema; the description partly compensates by explaining the revision precondition and the look_keys default ('default: all its looks'). The recipe_key is clarified as 'the named brief flow' from the current brief. However, brief_id and shot_index remain unglossed and 'Photo format is shared across the shoot' is an ambiguous hint rather than a stated parameter rule.

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 sentence states a specific verb and resource ('Append or replace one camera-view edit') and the scope of what gets revised ('selected looks using the named brief flow'). It is distinguishable from plan_shoot_edit/plan_shoot_image/plan_shoot_video by 'camera-view edit' and 'Photo format is shared across the shoot', though it never explicitly names those siblings.

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 a clear context (correcting camera framing on a planned shoot), states the append-vs-replace choice up front, and surfaces the prerequisite 'requires the current brief revision'. It also carves out what this tool is NOT for via 'No media generation, credit charge or library change', but it never names the alternative tool to use for those cases.

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