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

With no annotations, the description carries the full behavioral burden. It does add one genuinely non-obvious behavior: shots inherit the scene's location unless they override it, which tells the agent that this update has cascade effects. It omits the rest — that expectedVersion implies optimistic-lock failure on stale writes, that locationId=null clears the assignment, and whether changes are reversible.

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?

A single sentence that leads with the verb and resource, lists the editable fields inline, and puts the cascade caveat in a parenthetical at the end. Nothing repeats the schema and nothing is padding.

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 eight-parameter mutation tool with no annotations and no output schema, the description covers the editable surface and the one surprising side effect (location inheritance), which is more than most. It stops short of describing the version-check failure mode or the null-clears-location rule, so an agent could still get a write rejected without understanding why.

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 only 13%, so the description is doing most of the work for parameters, and it does name five of the eight (title, summary, narrativePurpose, plannedDurationMs, locationId). But it never explains the required expectedVersion parameter, the most consequential one for a mutation tool, nor does it state units for plannedDurationMs, leaving the three required plumbing params undocumented anywhere.

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?

Names a specific verb and resource (update a scene) and enumerates the mutable fields: title, summary, narrative purpose, planned duration, location. Clear enough that an agent won't confuse it with scene.create or scene.delete, but it does nothing to distinguish it from scene.reorder, storyline.update_scene, or shot.update, which overlap on 'edit scene content'.

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?

No when-to-use guidance at all: no mention of when to prefer scene.update over storyline.update_scene or scenario.apply_to_timeline, no stated prerequisites (project must exist, caller must own it), and no note about the concurrency contract implied by expectedVersion. The agent must infer everything from the name and schema.

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