finops_unit_economics

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds a real behavioral trait beyond them: it is a pure local calculator that does no price lookups or guessing, which tells the agent results are fully determined by its inputs and repeatable. It stops short of describing output shape, but an output schema exists for that.

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 filler, with the computed outputs front-loaded and the input-provenance caveat placed last. Every clause contributes information the schema does not already state.

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 output schema relieves the description of explaining return values, and the input-provenance note covers determinism. But for a 6-parameter tool with zero schema descriptions, gaps remain: the 'primary unit' concept in targetCostPerPrimaryUnit is undefined, and period/currency semantics are left entirely to the 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 description coverage is 0%, so the description must carry the parameter burden, and it partially does: units (request/customer/transaction) map to the units array, and the fixed-vs-variable split and 'target' map to fixedCosts, variableCosts and targetCostPerPrimaryUnit. It does not clarify what period means, nor which entry in units is the 'primary unit' that targetCostPerPrimaryUnit is measured against, leaving genuine ambiguity.

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 (compute) with three named outputs: cost per unit, fixed-vs-variable split, and the volume where marginal cost crosses a target. That is far more specific than a tautology, but it never names the sibling it should be chosen over (e.g. cost_model or capacity_plan), so an agent still has to infer the boundary from the last clause.

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?

"Caller supplies costs; no provider prices are guessed" is a usable selection signal: use this when you already have your own cost inputs rather than when you want priced AWS services. However, no when-not condition or alternative tool is named, so the guidance remains implied rather than explicit.

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