creative_studio_edit_visual

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

No annotations are provided, so the description fully bears the responsibility of behavioral disclosure. It details the output (edited PNG file written next to input with a specific naming pattern, returns path, SHA-256, and provider), and clarifies that the model does not render text. No contradictions exist.

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 description is two sentences with no filler. The first sentence establishes purpose and workflow ('art-direction loop'), the second details output and limitations. Every word adds value.

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?

Despite the tool's complexity (editing with multiple providers, file generation), the description covers the process, output format (filename, return data), and behavioral constraint (no text). No output schema exists, but the description adequately explains return values.

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?

All 3 parameters have schema descriptions (100% coverage), but the description adds value beyond the schema. It notes that 'path' expects a PNG, that 'provider' defaults to the first capable one, and that 'instruction' is for imagery-only changes. This enhances understanding without being redundant.

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 clearly states the tool refines an existing key visual using an image provider's edit path, specifically for the art-direction loop. It distinguishes itself from sibling tools like creative_studio_generate_visual (which creates new visuals) by focusing on editing and re-scoring.

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 provides context for when to use the tool (fix weak visual, re-score) and emphasizes that text is not rendered, guiding the agent to use it only for imagery changes. It doesn't explicitly list alternatives, but the sibling naming implies generate_visual is for new creations.

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