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

Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety and repeatability. The description adds meaningful context beyond annotations: the exact decimal format of the returned strings, and the clarification that task creation does its own funds check. This helps the agent understand precision expectations and when calling is redundant. It doesn't mention rate limits or latency, but those are not expected for a simple balance query.

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. The first sentence front-loads the primary purpose and output format; the second adds a critical usage note. No filler or redundancy. Every word contributes.

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 read-only tool with an output schema, the description fully covers what an agent needs to know: what is returned (three balance components in exact decimal strings), when to use it, and when not to. The output schema presumably details the structure, so the description doesn't need to. No critical information is missing.

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 per guidelines is 4. The description correctly omits parameter details since there are none to explain. No value is lost from lack of parameter documentation.

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 explicitly states the tool's function: returns available, held, and total balance as exact decimal USD strings. The verb 'Return' plus resource 'balance' is specific, and it clearly distinguishes the purpose from sibling tools (none of which are balance-related). No ambiguity remains.

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 clear usage context: use when balance is requested or when diagnosing funds. It also explicitly states that this is not a prerequisite for task creation because task creation already checks funds, which prevents unnecessary calls. It doesn't name an alternative tool because none exists, but the exclusionary guidance is valuable.

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 cover safety (readOnly, idempotent, not destructive). The description adds valuable scope context: it is limited to a 'bundled index' and 'verified first-party' URLs, indicating a closed-world search rather than open web search. This is useful behavioral information beyond 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, front-loaded sentence with no waste. It immediately states the verb and the resource, making it highly scannable and concise.

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 and has an output schema that presumably covers return values. However, the description omits any detail about how to use the parameters or what the search scope entails beyond 'bundled index'. While not critical for a basic search tool, the lack of parameter explanation and any edge-case notes makes it slightly incomplete.

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 explain parameters. It does not mention 'query' or 'limit' at all. While the parameters are relatively simple, the description provides no meaning beyond the schema's type/default information, failing to compensate for the coverage 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 clearly states a specific action ('Search') applied to a specific resource ('the bundled index of verified first-party documentation URLs'). It distinguishes the tool from siblings like service status, model listing, or task management, making it unambiguous.

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?

No guidance is provided on when to use this tool versus alternatives. There is no mention of alternatives or conditions that would make this tool the preferred choice. The description only states what it does, leaving the agent to infer usage context.

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 indicate this is not read-only and not destructive, and the description adds 'short-lived signed URL' and ownership context. However, it does not disclose expiration duration, whether creating the URL incurs costs or triggers a ticket, or any side effects. It also does not clarify whether calling this tool is itself a 'ticket call' – the mention of ticket calls is ambiguous. These gaps leave behavior partially unspecified beyond the 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?

Two sentences with no filler. The first sentence states the core purpose, and the second delivers usage guidance. Efficient, front-loaded, and every clause 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?

With an output schema present, return format need not be covered. But the description omits explanation of the 'key' parameter, which is essential for selecting the right output, and leaves the ticket-call relationship vague. For a tool with only 2 params and clear guidance, it is adequate but not complete.

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. It implicitly references taskId ('owned by the current task') but never mentions the 'key' parameter, its purpose, or how to choose among multiple outputs. The description adds minimal meaning for taskId and none for key, leaving parameter semantics largely unexplained.

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 and resource: 'Create a short-lived signed URL for an output owned by the current task and API key.' It also distinguishes itself from sibling tools like task_get and task_wait by positioning itself as a fallback for 'legacy integrations or explicit link renewal,' making its unique role clear.

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 when to use this tool ('for legacy integrations or explicit link renewal') and when not to ('Prefer existing ready output.assets[].url from task_get, task_wait, or a verified v2 webhook'). It names the alternatives and states no ticket call is needed for those links, giving clear routing guidance.

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 cover readOnly, idempotent, and non-destructive behavior. The description adds that the input schema is plain JSON Schema with display-only and rate-card annotations removed, and that some input values change the price. This goes beyond annotations and gives actionable context about the data 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?

Three sentences, front-loaded with the primary purpose, then usage and pricing caveats. Each sentence adds distinct value with no redundancy or 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?

Output schema exists, and the description covers purpose, input source, and pricing behavior. It also routes to task_create for exact quotes, leaving no critical information missing for correct invocation.

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 single 'model' parameter has no schema description (0% coverage). The description hints at how to populate it by referencing models_list ('Reuse a complete record already obtained from models_list'), but it does not explicitly state the expected format or that it is an identifier. This partially compensates but leaves room for clarity.

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 it returns one exact model with specific details (live input schema, pricing, policy, availability). It also distinguishes itself from models_list by instructing reuse of a record from that sibling, making the scope explicit.

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 guidance: reuse a record from models_list with includeSchema, and directs that task_create is for exact price quotes while this tool's pricing is for comparisons. This clearly informs when to use this tool versus 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?

Beyond readOnly/idempotent annotations, it discloses that returned schemas are plain JSON Schema with display-only and rate-card annotations stripped, and that some input values can change the final price. This manages expectations about the data and cautions against using list pricing as the final charge.

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?

Four sentences, front-loaded with the core purpose and followed only by high-value caveats. No filler or repetition of annotation/schema content.

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 behavioral caveats and sibling routing are strong, but with six undocumented optional parameters and no parameter descriptions, an agent cannot fully determine how to select a single model or use filters. Basic model-list calls are covered, but deeper use requires inference.

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 explain parameters, but it only explicitly covers includeSchema. The meaning of 'task' (how the 'selected model' is specified), search, modality, provider, and includeExamples is left to inference or the output 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?

States a concrete verb and resource: discover enabled models and account-specific prices. It differentiates itself from model_get by noting that includeSchema can avoid a separate model_get call.

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 contrasts with model_get ('without another model_get call') and routes exact-price confirmation to task_create. It tells agents to treat pricing entries as comparative, not authoritative charges, which is clear when-to-use guidance.

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 mark this as read-only and idempotent, and the description adds significant behavioral nuance: /readyz returns 404 by design on the public surface, readiness is registered only on the admin process, and 'operational' accounts for that. It also tells the agent not to report the 404 as an outage, which prevents a common misdiagnosis.

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?

Every sentence earns its place: the core function is front-loaded, followed by a clear usage caveat, an auth note, and a critical behavioral warning about 404 handling. The length is justified because it prevents a realistic false outage report.

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 an output schema availableable and annotations covering the safety profile, the description supplies the remaining operational context an agent needs: what to report, how to interpret 404, and the readiness endpoint's admin-only nature. Nothing essential is missing for correct invocation and interpretation.

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 zero parameters and the schema is empty, so the baseline is 4. The description does not need to document parameter semantics; it instead clarifies the input-free nature by noting no API key is required, which is sufficient.

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 uses a specific verb ('Read') with a clear resource ('public health and readiness endpoints') and the intended use ('diagnostics or an explicit status request'). This clearly differentiates it from the sibling tools, which cover docs, models, balance, usage, and task operations.

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 states when to use the tool ('for diagnostics or an explicit status request') and explicitly gives a when-not ('Not a prerequisite for task creation'). It also adds operational context with 'No API key is required,' giving the agent enough to decide when this tool is appropriate.

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?

Beyond the annotations, the description reveals important billing and failure behavior: it obtains a quote, shows USD estimate and maximum charge, reserves funds, creates an async task, and fails after the free quote without charging if form elicitation is unsupported. There is no contradiction with the annotations, and the description adds substantial context that annotations alone do not provide.

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 tightly written sentences with no filler. The primary workflow is front-loaded, and each sentence adds essential information: the creation flow, the task_quote exclusion, and the critical client-support failure condition.

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 the full call sequence, the money-related implications, the alternative to avoid, and the failure mode, which is enough for an agent to invoke the tool correctly. Given the presence of an output schema and annotations, the absence of a detailed return-value explanation is acceptable.

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 20%, and the description does not compensate by explaining the remaining parameters. The schema's retentionSeconds is well documented, but model, input, callBackUrl, and idempotencyKey receive no added meaning from the description, leaving a significant semantic gap for a low-coverage 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 states a specific process and resource: obtain an exact quote, show the USD estimate and maximum charge, reserve funds, and create an asynchronous task. It also explicitly distinguishes this from task_quote by instructing not to call task_quote first unless independently comparing prices, so an agent can select it correctly.

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 gives explicit when-to-use guidance: the tool performs quote, confirmation, and creation in one flow, and the agent should not call task_quote first unless independently comparing prices. It also warns that the tool requires an MCP client supporting form elicitation, and if that support is absent the call fails after the quote with no charge.

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?

Beyond annotations (readOnlyHint, idempotentHint, etc.), the description discloses critical behaviors: the assets URLs are directly usable without an API key, URLs may expire and require re-query, and unknown and inaccessible IDs both return 404. It also notes the webhook shortcut. 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?

Three sentences, each earning its place: the first states the core function, the second explains how to use the output URLs, and the third addresses webhook replacement and error behavior. It is front-loaded with the main purpose and contains 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?

With only one parameter, an output schema present, and rich annotations covering safety, the description addresses all operational needs: retry logic for pending/expired assets, the webhook alternative, and error handling (404 for any invalid ID). Nothing an agent needs to call the tool successfully is missing.

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 sole parameter 'taskId' is not described in the schema (0% coverage), but the description adds essential meaning: it refers to a task created by the current API key, and that unknown or inaccessible IDs yield 404. While it doesn't specify how to obtain the taskId (e.g., from task_create or tasks_list), it gives enough context for correct usage, compensating well for the schema 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 explicitly states 'Read a task created by the current API key' with a clear verb and resource, and adds a specific feature ('including ready output.assets[].url links') that distinguishes it from siblings like tasks_list (list tasks) and task_wait (wait for task). The purpose is unambiguous and separates it from alternatives.

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 usage context by noting 'A verified complete v2 webhook already contains the result,' implying when this tool is unnecessary, and advises to 'query again if assets are pending or URLs have expired,' giving retry guidance. It doesn't explicitly name sibling tools as alternatives, but the webhook alternative and retry conditions are clear enough for an agent to decide when to use it.

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 signal destructive and idempotent behavior, but the description adds substantial context beyond them: charges remain queryable, no refund or reversal occurs, no per-output granularity, the operation is irreversible, repeat calls are no-ops, and user confirmation is required. This fully discloses the consequence profile an agent needs before invoking a destructive tool.

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 dense but every sentence carries a distinct operational fact: destruction scope, cost-record preservation, irreversibility, download warning, terminal-state precondition, waiting path, idempotence, and confirmation. The most critical safety information is front-loaded, and there is no redundant 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?

For a destructive tool with no cancellation path, this description is operationally complete: it states preconditions, exact effects, non-effects, idempotence, required confirmation, and the correct workflow via task_wait. The output schema exists, so not describing return values is acceptable.

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 taskId's format and the rule to only use a user-named task. The description adds further selection semantics by requiring a terminal state and clarifying that the scope is the whole task, not individual outputs. That goes slightly beyond the baseline for high schema coverage, though it does not describe the parameter format itself.

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 verb and resource: 'Permanently destroy one terminal task's stored content,' and enumerates exactly what is destroyed. It also distinguishes itself from sibling tools by clarifying that it does not touch cost records or cancel tasks, so there is no ambiguity against task_wait or task_retry.

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 gives explicit when-to-use and when-not-to-use guidance: download wanted results first, only call on terminal tasks, wait with task_wait for queued/running tasks, and require user confirmation. It also states there is no cancellation API)Skip and no alternative for undoing, so the agent knows this is the only destructive path and how to sequence it 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?

Annotations already mark this as read-only, idempotent, and non-destructive, and the description adds further useful behavior: it creates no task, reserves no funds, and returns a five-minute USD estimate plus maximum charge. This goes beyond what annotations alone convey.

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 short sentences, each earning its place: one states the core action, one states the returned data, and one prevents misuse. The most important differentiator is front-loaded.

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 read-only annotations and presence of an output schema, the description covers the critical behavioral and usage context well. The main gap is parameter semantics, especially for the nested input object and optional callBackUrl, but the overall tool purpose remains clear enough for an agent to use 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 0%, so the description carries the full burden for parameter meaning, but it never mentions model, input, or callBackUrl. The phrase 'exact request price' hints that input represents the request, but the tool does not explicitly explain what each parameter is or how it shapes the quote.

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 action ('Compare an exact request price'), the resource (an exact SpicyAPI request), and key constraints ('without creating a task or reserving funds'). It clearly differentiates this from task_create and other task-related siblings.

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 tells the agent not to call this as a routine prerequisite because task_create already obtains its own quote and confirmation. It also implies the tool is for price comparison before deciding to create a task, giving clear usage context.

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 cover read-only, idempotency, and destructive hints, so the bar is lower. The description adds valuable behavioral context beyond annotations: the operation is billable, requires a user confirmation round, and creates a new task rather than modifying the source. No contradiction with annotations exists.

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 short sentences deliver the core action, trigger condition, and a critical prerequisite (user confirmation). Every word earns its place, and the essential purpose is front-loaded.

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 presence of an output schema and rich annotations reduce the burden, but important invocation details remain missing: what taskId refers to, how the idempotency key should be used, and what 'requires a user confirmation round' means in practice for an agent workflow. This is adequate but has clear 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 description coverage is 0%, so the description must compensate for the undocumented taskId and idempotencyKey parameters. It does not mention either parameter by name or explain idempotencyKey's role. The phrase 'from a failed or expired source' weakly implies taskId is the source task, but this is not explicit enough for an agent to invoke the tool with confidence.

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 action ('Create a new task') and a precise trigger condition ('from a failed or expired source'), making the tool's purpose clear and distinct from siblings like task_create or task_quote. The title adds the billable quality and confirms this is a retry path. The agent can confidently infer what this tool is for.

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 implies usage when a source task is failed or expired, and notes that a user confirmation round is required. However, it does not explicitly contrast with alternatives such as spicyapi_task_create for new tasks or spicyapi_task_get for inspection. The context is adequate but the exclusions are left to inference.

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/openWorld/idempotent/non-destructive behavior, and the description adds meaningful behavior beyond that: metadata-only responses, UTC half-open date intervals, defaults and maximums, stable cursor requirements, exact-but-settled cost semantics, and explicit non-polling/non-prerequisite characteristics. 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?

Every sentence carries a distinct, useful fact: scope, date semantics, pagination rules, limits, cost behavior, sibling routing, and exclusions. The core purpose is front-loaded, and the later caveats build context without repetition or padding.

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 output schema covers return shape and annotations cover safety/idempotency, the description supplies the remaining operational context: current-key scope, metadata-only behavior, date boundaries, cursor stability, limit defaults, cost finality, and clear exclusions. The only minor omission is explicit model/state filter semantics, but the schema names and enum mitigate that.

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 0%, so the description must compensate. It adds concrete semantics for from/to (UTC, half-open interval, default/max), limit (default/max), and cursor (fixed across pages), but it does not explicitly explain the model or state filter parameters. The state enum is self-describing and model is inferable, but the description is not fully exhaustive.

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 identifies a specific verb and resource ('Discover current-key task history') and adds the crucial qualifier 'with metadata only, without fetching each result.' It also differentiates itself from task_get and usage_get, so an agent can distinguish it from siblings without opening schemas.

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 gives explicit routing guidance: use task_get only for selected results and usage_get for settled spending including hidden tasks. It also preempts misuse by stating this is not a polling endpoint or a prerequisite to generation, plus gives pagination and date-window instructions.

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?

Beyond the readOnly/idempotent annotations, the description reveals concrete behavior: adaptive backoff from about 2 to 10 seconds, fixed intervalSeconds when provided, direct URL access, and non-cancellation on local timeout. There is 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?

Four compact sentences, each carrying new information: primary behavior, polling details, production alternative, and timeout caveat. The most important action is front-loaded.

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?

Annotations and output schema cover safety and return shape, and the description covers polling, timeout, and alternatives. It does not explicitly state what the tool returns if the timeout elapses or the task fails, which is a notable edge case for a wait tool, but the remaining guidance is strong.

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 only 33%, but the description compensates by defining timeout up to 300 seconds and explaining intervalSeconds' fixed versus adaptive behavior. It does not restate taskId, though that parameter is self-evident from the tool name and required field.

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 first sentence names a specific action and resource: wait for a task for up to 300 seconds and read ready output.assets[].url directly. It also distinguishes itself from sibling download-ticket and task_get flows by noting that no download-ticket call is needed.

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?

It gives explicit routing guidance: use this to poll and read output directly, skip the download-ticket call, prefer signed webhooks in production, and rely on a verified v2 callback rather than an extra task_get. The note that a local timeout does not cancel the task also tells the agent what not to assume after a timeout.

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 adds meaningful behavioral details beyond annotations: file size limits (10 MiB images, 90 MiB video/audio), the act of reading from this computer, uploading, and returning a URI. It does not contradict the annotations and gives useful operational context.

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?

Four sentences, front-loaded with the core purpose, followed by when to use it, size limits, and the alternative. No filler or redundant restating of the title or 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?

For a two-parameter tool with an output schema present, the description covers the action, the result (spicy:// URI), size limits, supported media categories, and the key alternative. Nothing essential is missing for an agent to call it 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 coverage is 100%, but the description adds value by clarifying that 'path' is an absolute path as given by the user and that 'contentType' is only needed when the extension is missing or wrong. This goes beyond the schema's own parameter 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 states a specific verb and resource: read a local file, upload it, and return a spicy:// URI. It clearly defines when the tool should be used ('whenever the user refers to a file on their machine') and distinguishes itself from the no-upload path for public HTTPS URLs.

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 is given for when to use this tool versus passing URLs directly. It also defines the alternative ('Public HTTPS media URLs need no upload at all') and gives media-type/size constraints, making the selection decision unambiguous.

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 declare readOnlyHint=true and idempotentHint=true, but the description adds unique behavioral context: money is returned as exact decimal strings, pending holds are excluded, late settlement can change prior-day spend, and rate limits should respect Retry-After. These details go beyond annotations and help the agent understand the reliability and semantics of the 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?

Every sentence carries weight: purpose, constraints, return format, exclusions, boundary clarification, and usage guidance. The most critical information (what it does and what it is not) is front-loaded. No redundancy 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 simplicity (2 optional parameters, read-only, idempotent) and that an output schema exists, the description covers all essential operational details: defaults, date range cap, return format, and exclusions. It is complete for an agent to call 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 coverage is 100% (both parameters have descriptions), so the baseline is 3. The description adds interval semantics (UTC [from,to), at most 92 days, defaults) which is useful beyond the schema. It doesn't dive into each parameter individually, but the added context justifies a 4 rather than a baseline 3.

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 begins with a specific verb+resource: 'Read task counts and settled actual USD spend for the current API key, grouped by creation day and model.' It explicitly distinguishes itself from siblings by stating it is not account balance or remaining key budget, and not a generation prerequisite. This leaves no ambiguity about what the tool does.

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 gives explicit use case: 'Use for requested usage reports.' It also states what it is not (balance, budget, generation prerequisite), effectively telling the agent when not to use it. This is sufficient guidance for selecting between siblings like balance_get.

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