Logospell

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety. The description adds useful context about the shared account balance, enhancing understanding without contradicting structured data.

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?

A single, front-loaded sentence conveys the exact purpose with no wasted words. The description is both concise and structurally effective.

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 zero-parameter tool with comprehensive annotations and an output schema, the description is fully sufficient. It adds the key nuance of a shared balance, covering all contextual needs.

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?

The tool has zero parameters, so the baseline is 4. There is no parameter description needed beyond the schema, which correctly shows an empty object.

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?

Description clearly states the tool checks remaining image generation credits, with specific verb 'Check' and resource 'credits'. The added detail about shared balance between MCP calls and the generate page distinguishes it from sibling generation tools.

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 context makes it obvious this is for verifying available credits before generation, but no explicit when-to-use or alternative comparisons are given. Since no sibling performs the same function, this is not a significant gap.

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

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

The description discloses extensive behavioral details beyond annotations: the upload URL and ref_ token workflow, the out-of-band HTTP PUT mechanism, the per-key privacy and rolling expiry window, cost implications, and the explicit rationale against embedding base64 in JSON. This is far more transparent than the minimal annotations.

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 dense paragraph but well-structured, moving from purpose to mechanics to constraints. It is slightly longer than necessary—some rationale (e.g., base64 context pain) could be trimmed—but every sentence contributes to operational understanding, so it remains efficient.

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 all essential context: return values, prerequisites (image format/size limits), the upload mechanism, the alternative shortcut, privacy/expiry behavior, and cost. Given the output schema exists and the description explains what is returned, it is fully complete for an agent to invoke correctly.

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?

While the schema covers parameter descriptions at 100%, the description adds meaning by explaining how sourceGeneration and sourceImage work together, that sourceImage is downscaled to fit, and that these parameters are the shortcut path that skips uploading. It also clarifies the token-based interaction with other tools' parameters.

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 with a specific verb and resource: 'Create an upload slot for a reference image.' It clearly distinguishes itself from siblings by stating 'This is the ONLY way to supply reference images,' making it unmistakable which tool to invoke for this purpose.

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 provides explicit guidance on when to use the tool versus alternatives: it is the only way to supply reference images, and when using one's own recent generations, the description directs to skip the upload and use sourceGeneration/sourceImage instead. It also notes the edge case of needing to resize images before uploading.

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

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

The description goes well beyond annotations by disclosing the zip return contents, 1-credit cost, single-flight execution per API key, short-lived download URL, client-side unpackTo semantics ('The server does NOT write here'), and max-size limitations. No contradiction with readOnlyHint=false or destructiveHint=false; it clarifies the client-side write workflow.

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 lengthy, every section earns its place: purpose, sibling alternatives, workflow, constraints, size table, formats, client-side file handling, and error behavior. It is front-loaded with the core purpose and decision criteria before diving into details.

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 7-parameter tool with an output schema, the description covers return format, side effects, constraints, rate-limit behavior, and post-call client responsibilities. It is self-sufficient and leaves no important operational gap for the agent.

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?

With 100% schema coverage, baseline is 3, but the description adds crucial semantics: supported width/height pairs, 'do not put pixel size in prompt', prompt-as-written behavior, 2500-character max, quality scope, filename default, and unpackTo's client responsibility. It provides the actual allowed values and usage nuances the schema alone does not.

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?

Opens with 'Generate a single composed illustration from a prompt' and enumerates use cases (scene, hero image, banner, character portrait, standalone picture). It clearly distinguishes itself from sibling tools by explicitly pointing to generate_image_set and generate_transparent_image_set for different image types.

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 states when to use alternatives: 'For a SET of separate isolated subjects... use generate_image_set... instead.' Also provides operational guidance: run generation calls sequentially, never in parallel, and wait suggested seconds on rate limit errors. This gives clear decision criteria and usage constraints.

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

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

Even though annotations already indicate non-readonly and non-idempotent, the description adds critical behavioral context: 'Each call costs 1 credit,' 'only one generation runs at a time per API key,' the automatic style/subject check behavior, the short-lived download URL, and the client-side responsibility for unpackTo. It also warns about rate-limit retry behavior. No contradiction with annotations.

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 front-loaded and logically structured, but it is quite long. Every sentence adds value, though there is some redundancy (e.g., background color prohibition appears in both the IMPORTANT rules and the background parameter description). For the tool's complexity, the length is mostly justified, but trimming repetitive guidance would earn a 5.

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 exhaustive for a complex tool: it covers cost, concurrency, output formats, size/quality tradeoffs, extensive style-and-subject authoring rules, validation behavior, rate-limit handling, and integration with create_reference tokens. It even provides a decision procedure for when to fix prompts and when to confirm with the user. This is as complete as one could hope for.

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?

While the schema already describes all 10 parameters (100% coverage), the tool description goes far beyond with usage semantics: size tradeoffs between native resolution and fixed sizes, validation mode scenarios, styleReferences ref_ token workflow, and subject distinctness rules. For example, it explains that omitting size delivers native resolution with higher quality, and that validation='skip' should be used when resubmitting approved prompts.

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 with a precise definition: 'Generate a cohesive SET of custom images on a SOLID-COLOR background, each one a separate isolated subject sharing one background and one visual style.' It clearly names the resource (image set) and scope (solid-color, isolated subjects, shared style), and distinguishes from sibling tools by explicitly routing transparent-background needs to generate_transparent_image_set and single composed scenes to generate_illustration.

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?

Provides explicit when-to-use guidance with named alternatives: 'For TRANSPARENT-background output, use generate_transparent_image_set instead' and 'For a SINGLE composed picture or a full-bleed scene, use generate_illustration instead.' It also instructs to 'Run generation calls sequentially, never in parallel' and details when to use validation modes (skip/auto-apply), making the decision tree clear.

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

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

The description discloses significant behavioral traits beyond annotations: each call costs 3 credits, returns a zip download URL, must be run sequentially, and has a validation workflow that may return suggestions. It also explains rate limit handling and that JPG is unsupported due to no alpha channel. No contradiction with annotations.

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 very long but well-structured with bold section headers. Each rule in the 'IMPORTANT' section serves a purpose for achieving isolated transparent subjects. Some redundancy exists in the don'ts list (e.g., multiple ways of saying 'no background'), but overall it is organized and the length is justified by the tool's complexity.

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 fully complete for the tool's high complexity: covers output format, return value (zip URL), cost, size/quality rules, validation flow, error handling, and the exact relationship between style and subjects. It also instructs the agent on resubmission with 'skip' after user confirmation, making execution robust.

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?

Despite 100% schema coverage, the description adds deep conceptual meaning: 'the style parameter says how everything is drawn; the subjects parameter says what to draw'. It explains styleReferences usage with ref_ tokens, validation modes ('skip', 'auto-apply'), and the caller's responsibility for unpackTo (downloading the zip). These go beyond the schema descriptions.

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 function: 'Generate a cohesive SET of custom images with TRANSPARENT backgrounds' with concrete use cases ('icons, logos, sprites, UI assets'). It distinguishes from siblings by mentioning the transparent background, the 3-credit cost, and the alternative generate_image_set for solid backgrounds.

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?

Explicit guidance on when to use this tool vs alternatives: 'If a solid colored background is acceptable... generate_image_set is 1 credit per call instead' and 'For a single composed scene... use generate_illustration instead'. Also provides operational guidance like 'Run generation calls sequentially, never in parallel'.

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

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

Annotations already declare readOnly, idempotent, and non-destructive. The description adds valuable behavioral details beyond annotations: billing occurs at completion, downloads remain available until original expiry, re-listing does not extend expiry, and listing costs no credits. This exceeds the safety profile provided by annotations.

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 appropriately sized for the information it conveys. Each sentence adds distinct value: purpose, use case, billing/expiry caveat, web page inclusion, return format, and cost. It is front-loaded with the primary action and remains easy to scan.

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 simple list tool with an output schema, the description is highly complete. It covers the exact use case, important billing semantics, non-extension of expiry, inclusion of web-page generations, output ordering, and field composition. No significant gaps remain.

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?

The input schema already fully describes the single 'limit' parameter with default and max. The description does not add further parameter-specific details, though it does clarify output ordering (newest first) which indirectly helps interpret 'recent'. With 100% schema coverage, the baseline of 3 is appropriate.

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 lists recent successful generations and returns download URLs. It distinguishes itself from sibling generation tools by focusing on retrieval/recovery rather than creation, and from check_credits by focusing on generation history.

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 explicitly states when to use: to recover a generation whose result message was lost. It also provides a clear caveat (re-listing does not extend expiry) and clarifies that generations from the logospell.com page are included, giving comprehensive usage context.

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