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

Goes well beyond the annotations by explaining the exact side-effect scope: it only returns an entity_id with no portrait/body/description. It also discloses execution context ('Plain HTTP, no browser involved') and the non-obvious constraint that each character image slot accepts exactly one write, with a second call 500ing rather than overwriting.

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?

Although substantial, every sentence carries operational value: it front-loads the core behavior, then routes to the sibling, then gives a clearly ordered numbered list of follow-up calls. The format is efficient and scannable, with no filler or redundant restatement of the tool name.

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 is nearly complete: it states the return value (entity_id), the sibling alternative, and the required follow-up sequence. The only material gap is the undocumented 'account' parameter, which prevents the description from being fully self-sufficient for a correct first call.

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 0% and the description never mentions the required 'account' parameter. With one required parameter and no schema documentation, the description was expected to compensate, but it provides zero guidance on what account means, where to get it, or what format it should take.

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?

States a specific action ('Create a new, empty Flow character') and resource, and explicitly delimits what it does not do: 'no portrait/body, no description yet'. It clearly distinguishes itself from the higher-level sibling create_character_from_description, so an agent can tell which tool to invoke.

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?

Gives explicit routing guidance: 'for "make me a character from a description and generate its portrait", call create_character_from_description instead of this'. It also provides a numbered next-step sequence after obtaining entity_id, including the warning that reversing the order causes 500s, which is directly actionable.

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