Edit Image

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

Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds important behavioral context: the tool can time out on Claude.ai (20-40 seconds), it modifies existing images (not read-only), and the strength parameter controls preservation vs. creativity. It also reveals that arrows/boxes on the image can be referenced for targeted edits, which is behavior not obvious from annotations or schema. There is no contradiction.

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 information-dense and well-structured with clear sections (supported operations, args, returns, best practices, examples). It is longer than minimal, but every section earns its place: the Claude.ai warning is critical, the supported operations list differentiates semantics, and examples are directly useful for generating prompts. Minor redundancy exists between the bullet list of args and the schema, but the description's arg list is a helpful quick reference.

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 complex image editing tool with 8 parameters, no nested objects, and an output schema, the description is remarkably complete. It covers the tool's purpose, safety/timing caveats, alternative routing (seedream_submit), parameter semantics, prompt best practices, and example invocations. The output schema exists, so the Returns section is sufficient without going into deeper detail. An agent has enough information to select this tool, construct valid parameters, and anticipate behavior.

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 100%, so every parameter has a description in the schema. However, the tool description adds meaning beyond the schema by explaining the strength parameter's semantic range (0=ignore original, 1=strongly preserve) and by providing prompt-writing best practices, including an example of referencing marked areas. The parameter list in the description is a condensed version of the schema, so it doesn't add much beyond what schema already provides, but the strength guidance and prompt guidance push it above the baseline 3.

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 uses specific verbs (edit, modify, enhance, transform) with a clear resource (existing image) and names the underlying model (SeeDream 4.5). It distinguishes itself from siblings by explicitly contrasting with seedream_submit for Claude.ai users and by listing supported operations (addition, deletion, replacement, modification, style transfer), making the tool's scope unmistakable even among five sibling 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?

The description provides explicit when-to-use guidance: it tells Claude.ai users to use seedream_submit instead, and it lists concrete use cases with examples. It also offers best-practice instructions for writing edit prompts, which is actionable guidance for an agent deciding how to invoke the tool and construct parameters. This goes beyond simply stating purpose and explicitly names an alternative and exclusion condition.

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