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

Despite annotations already declaring openWorldHint=true and destructiveHint=true, the description adds crucial operational details: requires confirmed=true, refuses otherwise, contacts no backend, and auto-generates an X-Idempotency-Key to prevent double-charging. This goes beyond generic hints and explains the concrete safeguards.

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 tight sentences: the first states the purpose, the second explains the confirmation guardrail, and the third covers idempotency. No fluff, front-loaded, and highly 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 key aspects: paid nature, confirmation requirement, byte-identical constraints, and idempotency. However, it does not mention the return value (e.g., generation ID) nor explicitly instruct to call deepy_estimate_generation first, though the sibling list implies this workflow.

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 provides 100% coverage with detailed descriptions for every parameter, including byte-identical constraints and idempotencyKey behavior. The description's mention of 'byte-identical' and 'auto-generated idempotency key' mirrors existing schema text, so it adds little new parameter-level meaning.

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 uses a specific verb ('Start') and resource ('generation'), and the word 'PAID' immediately distinguishes this from estimate, list, or get operations. It clearly states the tool's core purpose and differentiates from siblings like deepy_estimate_generation.

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 clearly states the prerequisite (confirmed=true) and the behavior if not met (refuses, no backend). It also implies the need for a prior estimate via 'byte-identical to the estimate', but it does not explicitly name the estimate tool as the prerequisite or list when-not-to-use alternatives.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently states that the tool does not charge anything and returns the token cost and balance. It also discloses the critical constraint that the params must match deepy_create_generation (quote == charge). However, it does not mention error handling, side effects beyond charging, or rate-limit implications, so a small gap remains.

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 three sentences, each with a clear purpose: what the tool does, when to use it, and the critical constraint. There is no wasted wording, and the most important information is front-loaded in the first sentence.

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 tool is relatively simple, and the description covers its purpose, return value (integer token cost and resulting balance), and the no-charge behavior. It also provides workflow guidance. While there is no output schema, the description sufficiently explains what to expect. Minor omissions like error cases or balance ownership prevent a perfect score.

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 provides 100% coverage with detailed descriptions for each parameter, so the baseline is 3. The description adds meaningful cross-tool semantics by emphasizing that the exact same params must be passed to deepy_create_generation. This generalizes the schema's note about prompt text to all parameters, thereby enriching the understanding of how these parameters are used.

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: to get the integer token cost and resulting balance for a generation without charging. The verb 'Get' and the specific resource 'token cost and resulting balance' make it unambiguous. It also distinguishes itself from the sibling tool deepy_create_generation by explicitly stating it does not charge.

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 tool provides explicit usage guidance: 'Always estimate and confirm with the user before creating' tells the agent exactly when to invoke this tool. It further instructs that the same params must be passed to deepy_create_generation, defining the workflow between the two tools. This is clear, actionable, and differentiates the estimate step from the actual creation.

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?

With no annotations, the description carries full burden. It discloses that the tool returns status, error info, and result indexes, and that it should be polled until a terminal state. However, it does not describe potential side effects (likely none), error response structure, or what happens with an invalid publicId. This is adequate but not deeply transparent.

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, information-dense sentence that front-loads the action and includes a concise polling directive. No wasted words; every clause adds value.

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 no output schema, the description explains the main return elements ('status, error info, and result indexes') and the polling lifecycle. It does not enumerate possible statuses, but the phrase 'until status is COMPLETED or FAILED' implies multiple statuses. This is reasonably complete for a simple one-parameter polling tool, though it could mention how result indexes are used with sibling tools.

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 100% (publicId is described as 'The publicId returned by deepy_create_generation'). The description reinforces this by saying 'by publicId' and 'result indexes by publicId,' but adds little beyond the schema. Baseline 3 is appropriate since the schema already fully documents the parameter.

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 fetches a generation's current status, error info, and result indexes by publicId. It uses a specific verb ('Fetch') with a specific resource, and it distinguishes itself from siblings like deepy_get_result (which likely retrieves actual results) and deepy_create_generation.

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 instructs to 'Poll this after create until status is COMPLETED or FAILED,' providing clear when-to-use guidance. It does not explicitly name alternatives or exclusions, but the polling pattern and sibling tools (e.g., deepy_get_result) imply when not to use this tool.

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?

With no annotations provided, the description carries the full burden of behavioral disclosure. It proactively states that closed/unknown models return MODEL_NOT_FOUND and that closed models are never revealed. This is meaningful transparency about error behavior and policy. However, it does not mention authentication, rate limits, or other side effects, but for a read-only fetch this is acceptable.

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 two sentences, front-loaded with the main purpose, and includes a critical behavioral note. Every sentence adds value with no redundancy.

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 single-parameter tool with no output schema and no annotations, the description covers the purpose and error behavior adequately. It lists the contents of the returned schema, which is sufficient. It does not describe the exact response format, but that is not required given the absence of an output schema.

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 100% and the schema already documents 'modelName' with an example. The description does not add any additional parameter semantics beyond restating the purpose. Baseline 3 is appropriate because the schema does the heavy lifting.

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 states a specific verb ('Fetch') and resource ('full schema for one model'), listing concrete contents (parameters, reference-file limits, generation type, max prompt length). This clearly distinguishes it from siblings like deepy_list_models (which lists models) and deepy_get_generation (which fetches generation results).

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 makes clear when to use it: to fetch schema details for a specific model. It does not explicitly name alternatives or exclusion criteria, but the context implies it is the tool for single-model schema lookup. The sibling list reinforces this by contrasting with list_models, yet no explicit 'use this instead' guidance is given.

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?

With no annotations provided, the description carries the full burden and delivers extensive behavioral detail: the server uses its own API key, saves the file locally and returns its path, inlines small media as base64, streams large/video media directly, handles arbitrarily large files, and never exposes the API key or raw URL. This goes far beyond basic expectations.

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 bit dense, containing four sentences, but every sentence provides essential behavioral or security information. It is front-loaded with the core purpose, and while it could be slightly more streamlined, it remains efficient and free of fluff.

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?

Despite being a relatively simple tool with two parameters and no output schema, the description fully covers return behavior (path vs. inline base64 vs. streaming), handling of large media, and security guarantees. It provides everything an agent needs to invoke and understand the outcome, leaving no significant gaps.

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 100%, with both parameters clearly described in the schema. The description adds the context that the result media belongs to a COMPLETED generation, reinforcing publicId, but does not add meaning beyond the schema. Thus baseline 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 opens with 'Fetch a COMPLETED generation's result media,' using a specific verb and resource, and clearly distinguishes from the sibling tool deepy_get_generation by focusing on the actual result media rather than the generation status or metadata.

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 emphasizes that the generation must be COMPLETED, providing clear context for when the tool is appropriate. It does not explicitly name alternative tools or state when not to use it, but the prerequisite and scope are clear enough for an agent to choose correctly.

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?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It warns that the rewriter can invent style references that do not exist, which is a critical transparency disclosure. It also clearly states the tool returns improved prompt text, making the output behavior explicit. Missing details about rate limits or cost, but for a simple prompt rewrite this is sufficient.

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 two concise sentences that are front-loaded with the main purpose. The first sentence states the action, the second gives usage and a critical warning. Every word earns its place, with no unnecessary repetition or filler.

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 low complexity and well-documented schema, the description is highly complete. It explains the return value (improved prompt text), its intended usage (base for estimate/create), and provides a crucial warning about potential inaccuracies. This is sufficient for an agent to select and invoke the tool correctly without additional information.

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 provides complete descriptions for all parameters, including style hints, prompt, and modality. The description does not add significant meaning beyond what the schema already covers, such as elaborating on how style interacts with modality. With 100% schema coverage, a baseline score 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 rewrites a draft prompt into a stronger one for a given modality, using a specific verb (rewrite) and resource (draft prompt). It distinguishes itself from sibling tools like deepy_create_generation or deepy_list_models, as it's specifically about improving prompts rather than generating or managing resources.

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 says to use the improved prompt as the base in estimate/create, giving clear context on when this tool fits in the workflow. It also advises reviewing the output first, which is important usage guidance. However, it does not explicitly mention when not to use this tool or alternative options, so it falls short of a full 5.

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?

With no annotations, the description carries the full burden and does well: it discloses that only opened/available models are returned, grouping by generation type, the `[refs]` marker for reference-file support, and that one call suffices (no truncation/pagination). It does not cover auth, rate limits, or error conditions, so it is not perfect, but it exceeds minimum viability.

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 four sentences, front-loaded with the core action, and every sentence earns its place: it adds availability scope, grouping, refs notation, and usage guidance without redundancy. The use of backticks for `[refs]` is clear and compact.

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 listing tool with no required parameters, no output schema, and no annotations, the description is complete enough: it tells the agent what is returned, the grouping behavior, the refs marker, and that one call is sufficient. It does not describe the exact response format, but that is not essential given the tool's simplicity and the high schema coverage.

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 schema already covers all three parameters with 100% description coverage, so the baseline is 3. The description adds value by explaining the purpose of the filters ('pass type/family/group only to narrow the catalogue') and explicitly says they are not for compensating truncation, which enriches the semantics beyond the schema.

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 'List the AI models available to your Deepy API key', a specific verb and resource, and adds scope details: 'only opened/available models are returned'. It also differentiates from sibling tools by noting grouping and refs markers, making its purpose distinct.

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 instructs 'Use this before estimating or creating a generation', providing clear when-to-use context. It also warns 'never to work around a truncated result', which is a when-not. However, it does not explicitly name alternative sibling tools like deepy_estimate_generation or deepy_get_model, so it stops short of a 5.

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 indicate readOnly and non-destructive, so the bar is lower. The description adds valuable context beyond annotations: it opens a browser page, returns its URL, and explicitly clarifies no financial transaction occurs. This meaningfully supplements the structured hints.

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?

Two sentences, no fluff. The first sentence states the core action and return value; the second provides usage trigger and a crucial safety clarification. Every sentence earns its place.

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 tool is simple (zero params) and the description covers its purpose, trigger conditions, side-effect-free nature, and return value. No output schema exists, but the description explicitly mentions what it returns, making the tool fully understandable.

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?

There are no parameters, so the baseline is 4. The description adds no parameter details because none exist, but it does specify the tool's return value (the URL), which is useful. No gap.

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 uses the specific verb 'Open' plus the resource 'Deepy credits top-up page', and adds the exact behavior: opening in the default browser and returning the URL. This clearly distinguishes it from sibling generation tools like deepy_estimate_generation and deepy_create_generation.

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 call: when a balance is too low to cover a generation, citing deepy_estimate_generation returning canAfford=false or a create failing with INSUFFICIENT_CREDITS. It also gives a clear exclusion: 'Opens a page only — it never moves money or charges anything.'

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 (openWorldHint, idempotentHint, destructiveHint) are generic. The description adds useful behavioral details: file size limit (50 MiB), the return value (fileId), and the distinction between filePath and base64 (preferred vs fallback). This goes beyond the annotations without contradicting them.

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?

Two dense sentences, front-loaded with the primary action and constraints. Every clause adds useful information—size limit, return value, when to call, and how to pass filePath. No fluff.

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 4 parameters and no output schema, the description covers the workflow (call before estimate/create), the accepted media types, size limit, and the two input strategies (filePath vs base64). It provides enough context for an agent to select and invoke the tool 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?

Schema description coverage is 100%, so the schema already thoroughly explains each parameter. The tool description adds marginal value (e.g., emphasizing filePath for agent-window files) but does not substantially augment the schema's per-parameter guidance. 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 opens with a specific verb and resource: 'Upload an image, video, or audio attachment... to Deepy and return its fileId.' This clearly distinguishes it from siblings like deepy_list_models or deepy_estimate_generation, which serve different purposes.

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 call: 'Call this before estimate/create and pass the returned id in referenceFiles.' It also provides context for filePath with attachments from the agent window, giving clear actionable guidance on how to supply the required input.

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