prepare_image_request

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that the tool does not contact the provider, which is a key behavioral trait (non-mutating). However, it does not describe the output format (e.g., whether it returns the JSON payload, any validation results, or errors). For a preview tool, this basic information is valuable but incomplete, as it leaves uncertainty about what exactly will be returned.

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 a single sentence and is front-loaded, but it is severely under-specified for a tool with 17 parameters and no annotations. It lacks any structural breakdown or elaboration on usage, output, or behavior. The brevity is not conciseness but rather an omission of critical information. A tool of this complexity requires a fuller description.

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 (17 parameters), lack of annotations, no output schema, and low schema coverage, the description is woefully incomplete. It provides only a high-level purpose without any context about how to use the parameters, what the preview looks like, or how it relates to generate_image. This is insufficient for an agent to correctly invoke the tool with meaningful parameters.

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 only 18%, meaning the schema leaves 82% of parameters undocumented. The description provides zero parameter details, failing to compensate for the low coverage. With 17 parameters, the lack of any explanation about parameters such as 'n', 'size', 'model', 'stream', etc., leaves the agent unable to construct a valid request without external knowledge. The description adds no semantic value beyond the schema's minimal annotations.

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 clearly states the tool's purpose: 'Preview the outgoing JSON without contacting the provider.' It uses a specific verb ('preview') and resource ('outgoing JSON'), and distinguishes itself from sibling tools like generate_image by indicating it does not contact the provider. This is a clear and unambiguous purpose statement.

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 offers no explicit guidance on when to use this tool versus alternatives. It does not mention that this should be used before generate_image to validate requests, nor does it provide any exclusions or conditions. The context of 'without contacting the provider' implies a dry-run use case, but that is not stated explicitly. No alternatives are referenced, so the agent must infer the usage pattern.

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