kie_estimate

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

With no annotations, the description carries the full burden of behavioral disclosure. It successfully discloses that the tool spends no money, may return an unknown price (known=false), and that certain models resolve exact prices only when passed matching input/refs. It also references missingFields in the response, hinting at conditional behavior. However, it omits details about error handling or what the full response contains, so it is not exhaustive.

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, front-loaded with the core purpose. The second sentence ('Spends no money') is highly informative and concise. The third sentence is long and dense, but every clause carries essential conditional logic. It is efficient and not padded, though a slight structural break would improve readability.

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 there is no output schema and no annotations, the description needs to explain the response and edge cases more fully. It mentions missingFields, known=false, and priceBasis, but does not describe the overall response shape, how to interpret cost values, or what to do when missingFields indicates issues. It is adequate for a basic call but leaves operational gaps for an agent needing to make decisions.

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 covers 75% of parameters with basic descriptions, and the description adds significant meaning by instructing that input and refs must match the generation parameters exactly for accurate range-based estimates. This helps the agent understand how to fill the undocumented 'input' object and clarifies the purpose of 'refs'. The description thus goes beyond schema in defining parameter relationships.

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 'Cost estimate before generation,' which is a specific verb+resource statement that clearly distinguishes it from sibling tools like kie_generate (actual generation) and kie_balance (balance check). It also states 'Spends no money,' further differentiating its purpose as a non-mutating pre-flight check.

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 guidance on how to use the tool: pass the same input and refs that will go into kie_generate, implying this is a pre-generation step. It also gives conditional usage rules ('If known=false ... generation must not start without user confirmation') and a conditional for priceBasis="range". However, it does not explicitly state when NOT to use it or name alternative tools, so it misses the full 'when/alternatives' ideal.

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