estimate_batch_cost

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

With no annotations, the description carries the full burden. It discloses one genuinely useful behavioral fact — that the tool is gated behind a Kiln Pro plan — but says nothing about whether the call is a pure computation with no side effects, whether it writes a cost record, or what it returns. The 'calibration that learns your printer, mid-print edits, unlimited textures' lines describe the Pro plan generally, not this tool's behavior.

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 purpose is correctly front-loaded in sentence one, but the remaining three lines are plan marketing and an agent-attributed upgrade URL that contribute nothing to correct invocation. Roughly three quarters of the text is noise against a single useful 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?

For a 4-parameter tool with an opaque nested object, no annotations, and no output schema, the description should explain the decoration_cost shape and the meaning of the total (per-unit vs batch, which cost components are included). Instead it spends its budget on upgrade messaging, leaving the primary invocation details unresolved.

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 50% and the two required parameters are the undocumented ones: num_units has no description at all, and decoration_cost is a free-form nested object with additionalProperties: true whose expected keys are defined nowhere. The description adds zero parameter meaning, leaving the agent unable to construct a valid decoration_cost payload.

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 opening sentence gives a specific verb and resource — 'Estimate total cost for a batch of decorated items' — which is enough to distinguish it from single-item estimators like estimate_decoration_cost. However, it never names its closest siblings (batch_estimate_plate_part_costs, estimate_cost, estimate_decoration_cost) or states the scope difference, so the agent must infer which batch estimator applies.

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?

There is no guidance on when to prefer this over estimate_decoration_cost, estimate_cost, or batch_estimate_plate_part_costs, which all sound similar. The only usable signal is 'Requires Kiln Pro', which is a gating prerequisite rather than a usage rule, and the rest is feature marketing.

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