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

Beyond the annotations (non-readonly, non-idempotent, non-destructive), the description discloses real behavioral traits: the operation costs credits, is paid-only, takes about a minute, allows 3 retries, and enforces one mascot per workspace. This is exactly the kind of non-obvious context that helps an agent manage side effects and expectations.

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 but economical: it front-loads the core purpose and then packs the essential workflow into a single trailing sentence. The semicolon-heavy structure and parentheticals are slightly compressed, but every clause carries useful information and there is no 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?

The description covers cost, async polling, follow-up actions, retry limits, input modes, and workspace constraints. Given that the input schema is fully documented and an output schema exists, nothing critical is missing for an agent to correctly initiate the flow and hand off to get_mascot/mascot_step.

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 the baseline is 3. The description adds value by grouping parameters into two semantic modes: 'description (note, kind)' and 'reference picture' (which maps to image_url/image_base64). It also confirms that style and name are part of the creation brief without re-listing every schema property.

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 opens by naming the action and resource: 'Start the brand mascot'. It then distinguishes two input modes (description versus reference picture), which clearly separates it from related siblings like get_mascot (polling) and mascot_step (follow-up). This is a specific verb-plus-resource statement with no ambiguity.

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 workflow context: call this first, poll get_mascot, show the human, then use mascot_step to keep or retry. It also frames the creation decision via description versus reference picture. It does not explicitly list alternative tools to avoid, but the sequential guidance and 'One mascot per workspace' constraint are enough to guide an agent.

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