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

The description extensively discloses behavioral traits beyond annotations: it returns a served URL, composites product images when refImages are provided, decides the rendering engine based on whether references are attached, and passes prompts byte-identically when raw:true. It also mentions speed ('Fast (seconds)') and cost ('Spends credits'). These add significant value beyond what annotations (which only say false for readOnly/destructive/idempotent) provide. 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 dense and lengthy, with multiple caveats and warnings (MULTI-BRAND CAUTION, RAW MODEL ACCESS). It focuses heavily on edge cases (brand mismatches, engine selection) which are important but verbose. While it starts with the core purpose, it quickly dives into complex scenarios. It is structured with clear headings and readable, but could be more concise by consolidating some repeated points (e.g., repeated mentions of model selection). It earns a 3 for being informative but not optimally concise.

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?

Given the tool's complexity (7 parameters, interactions between refImages, useBrand, raw, and model), the description is thorough and covers all critical aspects: brand hydration pitfalls, engine routing, raw model access, credits, and delivery. It even notes that the served URL is the return value, which compensates for the absence of an output schema. An agent can understand how to call this tool correctly and avoid common errors. Nothing major is missing.

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 already documents all parameters. The description adds extra meaning on top, especially for refImages, raw, and useBrand, explaining their interactions (e.g., how useBrand hydration affects the engine, how raw:true bypasses brand attachment). This goes beyond the schema's basic field descriptions, helping the agent understand nuanced behavior. A 4 is appropriate because it enriches, but the schema already provides baseline information.

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 starts with a clear verb-resource pair: 'Render a finished ad IMAGE and return its served URL.' It specifies the resource (ad image) and the outcome (served URL). However, it does not differentiate from sibling tools like render_ad or make_template_ad, which may also generate ad images. The phrase 'ad IMAGE' helps but is not enough to distinguish it from similar 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 detailed guidance on when to set specific parameters (e.g., when to pass refImages, when to use raw:true, when to use useBrand:false) based on the brand context and model selection. However, it does not explicitly state when to use this tool instead of alternatives like render_ad or make_template_ad. It gives context for parameter usage but not tool-selection guidance, so it falls short of the 'when to use this vs alternatives' requirement.

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