ModelCostComparison

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds substantive behavioral context beyond them: what is excluded (cache writes, storage, search, tool fees, taxes), that it does not invoke a model, that it requires current reviewed supported rates, and the double-counting caveat for cached input.

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?

Five tight sentences, front-loaded with the use case, then prerequisite, then inclusions/exclusions, then alternative. Every sentence carries distinct information with no 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 read-only calculation tool with a full output schema (so return values need not be explained), the description covers scope, prerequisites, exclusions, rate requirements, and sibling routing. An agent has everything needed to invoke 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%, so the baseline is 3, but the description adds real semantic value by clarifying that total input already includes cached input and warning not to add cached tokens twice. It does not add further syntax detail beyond what the schema already provides.

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 (calculate) and resource (cost) with precise scope ('USD text-token subtotal' for 'one exact offer ID and token usage'). It explicitly distinguishes itself from siblings by naming compare_model_costs for multiple offers and list_models for ID discovery.

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?

Gives an explicit trigger condition ('when you have one exact offer ID and token usage'), a prerequisite step ('Discover the ID with list_models first'), and a named alternative with its selecting condition ('Use compare_model_costs for several known offers'). Nothing is 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 only cover the safety profile (readOnly, idempotent, non-destructive). The description adds substantive behavior: the equal-token-count comparison assumption, that per-offer exclusions are returned, and an explicit exclusion list (cache writes, storage, search, tool fees, taxes), plus the caveat that it does not rank quality.

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 precondition, then caveats, then exclusions, then the sibling routing. Every sentence carries distinct, actionable information with no 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?

An output schema exists, so return shapes need not be explained, yet the description still flags 'supported results and per-offer exclusions'. Combined with the documented usage shape and the DATASET_CHANGED handling in the schema, an agent has everything needed to invoke and interpret it.

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 100%, so the baseline is 3. The description reinforces 'exact offer IDs' and 'do not supply display names' and the 2–20 bound, but these are already documented in the schema, so it adds little beyond reinforcement.

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 ('compare' cost subtotals for 2–20 exact offer IDs) and scopes it tightly. It is immediately distinguishable from discovery/ranking siblings like find_cheapest_models.

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?

Opens with the precise precondition (you already have 2–20 exact offer IDs) and names the alternative with the condition that selects it ('Use find_cheapest_models to search without a shortlist'). When-to-use, when-not, and alternative are all explicit.

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/non-destructive annotations, the description discloses the exact cost scope excluded (cache writes, storage, search, tool fees, taxes), that exclusion counts are reported, that the default tariff is standard, and that equal token counts do not imply tokenizer equivalence. These are non-obvious behavioral traits an agent cannot infer from the annotations or schema.

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?

It is a single dense paragraph that front-loads the usage trigger and then layers scope caveats; every sentence carries information. It would be easier to scan as short bullets, but there is no filler or repetition.

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 6-parameter ranking tool with an output schema and rich annotations, the description covers eligibility, cost exclusions, tariff defaults, capacity-filter semantics, and the tokenizer caveat. An agent has enough to invoke it correctly without guessing.

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 100%, so the baseline is 3, but the description adds meaning the schema does not: that capacity filtering reflects reviewed pricing input limits rather than full context windows, and that token-count parity across models is not tokenizer equivalence. It otherwise restates schema facts such as the standard-tariff default, keeping it below 5.

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 gives a specific verb and resource: rank eligible current reviewed offers by USD text-token subtotal and return their exact IDs. It also pins down what 'cheapest' means (within eligible catalogue and supplied filters, not quality or whole market), which helps separate it from compare_model_costs. It stops short of naming sibling tools, so it falls one notch below a 5.

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 opening 'Use when you know your token workload but have not selected offers' states a clear triggering condition, and the 'not best quality or the entire market' caveat bounds expectations. No alternative tool is named for the adjacent case (e.g., when you already have offers or want a pairwise comparison), so there is no explicit when-not routing.

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 readOnlyHint, idempotentHint, non-destructive, and closed-world behavior. The description adds meaningful context beyond that: prices are recorded USD text-token rates, and expired or unreviewed rates are informational only, which helps the agent interpret data freshness and reliability.

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 tightly structured: usage context and prerequisite first, parameter guidance second, data caveat third, and alternative tool last. Every sentence adds distinct value with no redundant or filler 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?

For a simple single-parameter lookup tool with full schema coverage, annotations, and an output schema, the description covers usage context, the alternative tool, and important data-freshness limitations. Nothing an agent needs to select or invoke the tool correctly 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?

Schema description coverage is 100%, and the schema's model_id description already explains that it must be the exact pricing-offer ID returned by list_models or find_cheapest_models. The tool description reinforces this with 'Supply the returned model_id' but adds no semantic detail beyond the schema, so the baseline 3 is appropriate.

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+resource: retrieving the rates, tariff identity, sources, and freshness of one exact offer. It explicitly distinguishes itself from calculate_cost (workload estimate) and implies its relationship to list_models, so an agent can tell it apart 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?

It says to use this tool after list_models and when an exact offer is needed without calculating a workload. It names calculate_cost as the alternative for workload estimates, providing explicit when-to-use and alternative 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 declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuine context beyond that: default scoping to 'current reviewed offers,' that multiple tariffs surface as separate choices, and that non-current records may not support calculations — useful behavioral traits not captured by 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?

Front-loaded with the 'use first' trigger and dense with routing information, with no wasted sentences. It is slightly run-on with several clauses packed together, but every sentence carries actionable 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?

For a discovery/list tool with an output schema (so return values need not be explained), the description covers the when-to-use trigger, default scope, tariff behavior, and a calculation-readiness caveat. Nothing an agent needs to invoke it correctly 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?

Schema description coverage is 100%, so the schema already documents all six parameters including defaults, enums, and variant-tolerance. The description largely restates these (defaults to current, tolerates variants), adding little syntax or format meaning beyond the structured fields, so baseline 3 applies.

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 resource (pricing offers/models) and its outcome (exact pricing-offer IDs) with a clear verb implied by 'search recorded labels and API IDs.' It explicitly differentiates itself from siblings by noting it 'discovers pricing offers, not model capability recommendations' and positions itself as 'use first' for obtaining offer IDs.

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 prescribes when to use it ('use first when you know a model name or provider but need exact pricing-offer IDs for pricing or calculations') and gives a downstream prerequisite ('check costing_supported before calculating'). It also draws a clear boundary against non-pricing discovery use cases.

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/idempotent/non-destructive/closed-world, so safety is covered without help. The description adds genuine non-obvious data semantics: that the two rate minima may come from different offers, and that ranges are not capability rankings. It stops short of noting pagination or result-size limits, which keeps it from a 5.

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 tight sentences, front-loaded with the primary purpose, then the return shape, then the caveats and alternative routing. No filler or repetition; every sentence carries 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-value documentation is not required, yet the description still characterizes the payload. Combined with the sibling routing and the rate-range caveat, an agent has everything needed to decide whether to call this tool and how to interpret the result.

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% and both parameters carry their own descriptions, including the "omit for all providers" default behavior, so the schema does the heavy lifting. The description adds no parameter-level detail beyond that, matching the baseline 3 for fully documented schemas.

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 purpose ("discover provider IDs and catalogue coverage") and specifies the returned payload (distinct API model counts, offer counts, USD rate ranges), so an agent knows exactly what it gets. It also names the siblings it is not, e.g. find_cheapest_models and calculate_cost, making it separable from the other pricing tools.

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?

Gives an explicit trigger ("before filtering model searches") and explicit redirects for a different intent ("For a workload estimate use find_cheapest_models or calculate_cost"). It also warns what the tool is NOT for ("ranges are not capability rankings").

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