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

Annotations say readOnlyHint=false, destructiveHint=false, idempotentHint=false, so the agent knows it is a non-destructive write but not what it does; the description supplies the missing behavior: no credits are spent, no generation starts, other sections keep their choices, outputs fit the project canvas without cropping, the revised quote carries its own price and approval binding, and operationId dedupes identical retries. This is exactly the kind of side-effect and idempotency context annotations cannot express.

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 purpose and outcome before parameter guidance, and nearly every clause carries a distinct fact (restore vs preserve, canvas fit, approval binding, retry identity). It is dense to the point of being terse, with several facts stacked into single sentences, but there is little redundancy.

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 7-parameter mutation with a nested profile object, an output schema, and non-default annotations, the description covers selection semantics, cross-tool dependencies (studio_section_engines, studio_storyboard_context), retry behavior, and the credit/approval consequences. An agent has everything needed to invoke it correctly without extra lookups.

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 86%, so baseline would be 3, but the description adds semantics the schema lacks: the null-vs-omitted distinction for modelName, that profile values come from availableProfiles, that costEstimateId must be the exact estimate from the preceding quote, and that expectedRevisionId comes from studio_storyboard_context.

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 (selects) on a specific resource (one section's modelName or generation profile) and names the concrete outcome (a revised signed quote with costEstimateId). It is clearly distinguishable from studio_section_engines (the listing source) and from the generic quote tools.

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 concrete operating conditions: modelName:null restores the Recommended choice, omitting modelName preserves explicit selections during a profile change, profile is limited to availableProfiles, and Film must use the saved scene.index. It points at studio_section_engines as the source of valid names but never states an explicit when-not-to-use-this or a competing sibling to prefer.

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