generate_image_ai

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

With no annotations, the description carries the full burden and does so well: it discloses the side effect (writes a file to disk), the return value (file path), the trust boundary (requests pass through the BitPull server to third-party providers, not end-to-end encrypted), and the cost model (paid in BitPull credits). It does not cover latency, output format, or failure behavior for unsupported sizes or models.

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?

Front-loads the action, then the return behavior, then the security and billing caveats in three dense sentences with no filler. Each sentence contributes distinct information, though the provider-list parenthetical is slightly incidental.

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 3-parameter, no-output-schema, no-annotation tool, the definition covers the critical unknowns an agent would otherwise guess at: where the model ID comes from, that a file path is returned, that data transits a third party, and that credits are charged. The remaining gap is the size parameter, which is undocumented anywhere.

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%, so the description must compensate and only partly does: it explains where valid model values come from (list_ai_models, modality "image") but says nothing about the size parameter or prompt constraints (1–4000 chars). The model param gains real meaning; size is left entirely to a bare maxLength of 20.

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?

Names a specific verb and resource ("Generate an image") and scopes the model source to BitPull's proprietary models, which separates it from the text-oriented ask_ai_model / ask_group_model family by implication. It does not explicitly say what it is not, so sibling differentiation depends on the reader inferring from the sibling name.

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 a concrete prerequisite step: consult list_ai_models and pick a model with modality "image", which is real when-to-use guidance tied to another tool. It also states a clear do-not (no secrets or unagreed personal data) but never explicitly contrasts against the other ask_* tools.

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