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

Annotations only declare a non-read-only, idempotent, non-destructive, closed-world mutation. The description goes well beyond that: billable AI usage, durable execution, mutation modes (validate_only/preview_only/execute), a partial-failure policy of completed_items_not_rolled_back, automatic deterministic idempotency-key derivation on omission, and the hard rule that a write requires seatId/seatName on the exact call rather than a remembered seat. That is substantive operational disclosure an agent cannot get from the annotations.

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 purpose and usage rules are correctly front-loaded, but the text then appends a large block of generic response-formatting directives (assistantSummary, never display raw JSON, prefer human language) that reads as system-prompt boilerplate rather than tool-specific documentation. The title text is also duplicated verbatim into the description, including a stray double period, adding dead weight.

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 24-parameter billing mutation with a published output schema, the description covers the operationally decisive facts: that it bills, that execution is durable and not rolled back on partial failure, that it saves by default and returns preview links plus QA context, and that writes need an explicit seat. The main omission is version-conflict expectations around expectedVersion.

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% across 24 parameters, so the description must carry the load. It does explain the semantics of dryRun, the save-by-default behaviour, idempotencyKey derivation, and the seatId/seatName write requirement, but it leaves the highest-traffic inputs undocumented: prompt vs instructions, persistence vs saveToStudio, expectedVersion concurrency semantics, and the whole locale/market group.

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 gives a precise verb+resource+scope ('Revise an existing saved Studio creative by executing a requested change') and enumerates what is editable (copy, imagery, layout, colours, typography, CTA, branding). It is unmistakably a revision-in-place tool rather than a build/clone tool, though it never names the adjacent siblings (create_creative_version, clone_creative, restore_creative_version) that an agent might otherwise reach for.

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 an explicit trigger ('use this directly when the user supplies a creativeId and asks to change...'), an explicit anti-pattern ('do not respond with a copy-paste instruction or ask the user to make the edit in Studio'), and a narrow condition for dryRun ('only when the user explicitly asks for an unsaved preview'). The only gap is that alternative tools are not named or contrasted.

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