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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds behavior the annotations cannot express: it refuses stale revisions (optimistic-concurrency guard), rejects image IDs belonging to another profile (ownership constraint), and states that saving is free and performs no publishing or AI generation. It stops short of stating that the prior document is overwritten or what the failure response looks like.

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 — the act and its rejection rules come before the document-format detail — and nearly every sentence carries information that the opaque schema does not. The Panorama spec is delivered as one dense run-on paragraph with no structure, which makes it harder to scan than it needed to be.

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 a nested free-form document, no output schema, and 0% schema coverage, the description covers Panorama documents well but says nothing about the default document shape, what happens to prior content on save, or what a successful save returns. An agent calling this for a non-Panorama document is still guessing at the payload.

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 description coverage is 0% and 'document' is an untyped free-form object, so the description carries the burden. It compensates substantively for the Panorama case (slide label/heading/emphasis, the seven allowed block types with their fields, and 'zone' as pixels from the top of 1080x1350), and 'Refuses stale revisions' explains revision semantics. However projectId is never explained and the non-Panorama document shape is completely undocumented, leaving a real gap.

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 first sentence gives a specific verb and resource ('Save an edited Studio document at its current revision') and the save/revision scope immediately separates it from read-only siblings like studio_project or studio_list. It also names the downstream sibling studio_export, so an agent can place this tool in the studio workflow without opening either schema.

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 routing context: 'Manual editing is free. No publishing or AI generation occurs' steers the agent away from create_post and generation tools, and 'studio_export then sets the saved words exactly' establishes the follow-on call. There is no explicit when-not or prerequisite list (e.g. whether the project must already exist), so it falls short of full alternative coverage.

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