Estimate Task Price

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

Goes well beyond the readOnly/idempotent/non-destructive annotations: it explains that nothing executes, that max_price_per_hour caps only the compute rate while storage, Asset Hub retention and fetch-time charges are billed separately, and that the estimate is not a total-bill ceiling. It also discloses the output_include null-filter edge case, which is exactly the kind of surprising behavior an agent needs.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and the 'nothing runs' guarantee, then groups parameters logically. It is dense and some sentences run long (the output_include glob sentence), but nearly every clause carries operational information an agent would otherwise have to guess.

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?

An output schema exists so return values need no explanation, and the description covers the compute-pricing model, resource selection, and output filtering thoroughly. The remaining gap is the undocumented set of ancillary parameters (env, args, workspace, secret_keys, webhook_url, requirements) on a fairly complex 18-parameter tool.

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 0% schema coverage across 18 parameters the description carries the full burden, and it delivers for the important ones: script size limit and flush requirement, image/template_id, the mutually exclusive gpu_model vs cpu_preset choice with concrete preset examples, max_duration's 3600..86400 range, input_assets attachment syntax, and output_include glob semantics. However, env, args, workspace, secret_keys, webhook_url and requirements get no explanation at all, leaving roughly a third of the parameters undocumented anywhere.

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 specific verb and resource ('Estimate a one-off task's compute hourly price') and immediately bounds the scope with 'nothing runs', which cleanly separates it from submit_task and from estimate_pod. An agent can tell what it returns (a price) without opening the schema.

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 phrase 'before submitting it; nothing runs' gives a clear usage context and implies the pairing with submit_task, and the max_price_per_hour caveat warns about misusing the estimate as a bill ceiling. It stops short of explicitly naming submit_task as the follow-up or stating when estimate_pod would be preferred over this tool.

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