Studio Revise

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

No annotations are provided, so the description carries the full burden. It discloses that the operation creates a new artifact, does not modify the original, only supports slide decks, and is asynchronous (poll studio_status). It does not mention the confirm user-approval step, though that is documented in the schema.

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?

Three short sentences communicate the core action, the key constraint, the non-destructive behavior, and the follow-up polling step. Every sentence adds value with no repetition or 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 tool with no annotations, the description covers the most critical operational behaviors: it creates a new artifact, leaves the original intact, only works on slide decks, and requires polling status. Combined with the rich input schema and output schema, this is nearly complete; the only minor omission is explicitly stating the user-approval confirm flow in the description itself.

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 100%, so the schema fully documents all parameters including slide numbering, confirm requirement, and artifact_id origin. The description adds no per-parameter detail beyond the schema, which is acceptable given the high schema coverage but does not elevate the score.

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 description states a specific verb-resource pair ('Revise individual slides in an existing slide deck') and clearly distinguishes from creation tools by emphasizing 'existing' and 'Creates a NEW artifact.' It also names the poll step via studio_status, which separates it from studio_create and studio_delete.

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?

The description gives clear context: it applies only to slide decks, and it instructs the agent to poll studio_status after calling to check readiness. It does not explicitly name an alternative tool for creating a new slide deck, but the 'existing slide deck' phrasing and the sibling set make the intended usage evident.

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