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

Annotations declare non-readonly, non-destructive, non-idempotent; the description adds the materially important side effects: writes into project image history, consumes credits, and returns hosted URLs plus a preview for verification. It is slightly weakened by "more for higher tiers" when the modelTier schema states every tier currently bills as standard, a cost inconsistency an agent could act on wrongly.

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?

Three sentences, front-loaded with the action and persistence effect, then return values, then cost, then the alternative. Each sentence carries distinct decision-relevant information with no repetition of the schema.

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?

With no output schema, the description correctly spells out what comes back (hosted URLs + previews), and it warns about credit spend for a mutation-style tool. It falls short only on includeLogo and on the tier-cost statement, which the schema contradicts.

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 75%, with style, format, prompt, modelTier, projectId and adBackground already documented in-schema. The description adds the meaningful output linkage (URLs go to create_post) but does not compensate for the undocumented parameters, notably includeLogo, and its cost claim about tiers conflicts with the schema's modelTier note.

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?

Specific verb + resource ("Generates on-brand images") plus the persistence effect ("saves them to the project's image history"). It is clearly distinguishable from create_carousel, create_post and create_reel in the sibling list by naming image generation as its scope.

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?

Explicitly routes the agent away for a specific case: "For tips, steps or a list of points, a short styled carousel (create_carousel) reads better than one picture." It also names the downstream consumer of the output (create_post), so the agent knows where the result flows.

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