AI Rate Card

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

readOnlyHint already covers the safety profile, so the description only needs to add what annotations don't. It does add the sort key (input price) and the result shape (one row per model-provider pair), but says nothing about output fields or what happens when the catalogue has ties or sparse data. Adequate, not rich, against an already-declared read-only annotation.

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, front-loaded with the definition and followed immediately by sibling routing. No filler, and the disambiguation clause is the highest-value content placed first.

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 two-parameter read-only lookup with a fully described schema, the definition covers purpose, granularity, ranking key, and alternatives. Without an output schema, a brief note on returned fields would close the remaining gap, but nothing needed to call 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 coverage is 100%, so both limit and the category enum are already fully documented in structured data. The description's phrase 'one model type' echoes the category parameter without adding format or default details beyond what the schema states. Baseline 3 applies when the schema does the heavy lifting.

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 resource and ranking (cheapest current offers, one model at one provider, sorted by input price) and pins the row granularity explicitly. This makes it distinguishable from cheapest_models and cheapest_for_workload without opening any 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?

Names two alternatives and the selection condition for each (per-model aggregation, monthly workload), which is strong routing guidance. It does not address the other lookup siblings such as search_offers or get_model_prices, so an agent still has to infer when this beats a broader offer search.

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 cover read-only safety, but the description adds real behavioral context beyond them: results are the single best offer per model, non-standard price types and free promos are filtered out by default, and rows carry specific fields. It does not discuss pagination or result ordering ties, but the filtering defaults are the material behavior here.

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 front-loaded with the resource and ranking basis, then the input modes, then the filtering rules, then the row shape — a sensible order with no filler. The middle sentence is densely packed with several qualifiers, which is efficient but slightly harder to parse than a split would be.

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 12-parameter tool with no output schema, the description compensates by enumerating return fields (monthly_cost_usd, prices, context, checked_at, card_url, cite line) and explaining default filtering. The main residual gap is that it never says how ranking ties or empty results behave, but nothing essential for calling 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 coverage is 100%, so the baseline is 3; the description adds value by explaining that a preset "fills tokens, min_context, category" while "your own values win" — a precedence rule the schema does not encode. It also clarifies the default exclusion behavior behind include_free and include_special, though most other parameters are left to the schema.

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 a specific resource and scope: "The cheapest offers for a whole monthly workload, ranked by monthly cost in USD." The "whole monthly workload" framing distinguishes it from per-call/per-token pricing siblings such as cheapest_models or get_model_prices, so an agent can pick it 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?

It states the two input modes ("give a preset ... and/or your own tokens a month") and routes the agent to workload_presets for preset definitions. It also explains that free promos and batch/flex/priority/regional prices are excluded "unless asked," tying the flags to a use case. It stops short of explicitly naming when to prefer cheapest_models or estimate_cost instead.

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 declare readOnlyHint=true, so the description carries most of the burden and does add value: it discloses the dedup rule, the default pricing unit (input tokens), and the shape of a returned row (price, where it is, card_url). It still says nothing about ordering guarantees beyond 'n cheapest' or about tie-breaking, but for a read-only lookup this is solid extra context.

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 compact sentences with the core behavior front-loaded and no filler. The parentheticals ('for a job (task)', '(input tokens by default)') make it slightly dense but each carries information.

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?

There is no output schema, and the description compensates by describing the returned row contents. With all parameters documented in the schema and read-only behavior implied by annotations, the definition covers what an agent needs to call it, though it could say more about ordering and edge cases like fewer than n models existing.

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 all four parameters are already fully documented, including enum meanings and defaults. The description only reinforces the default component ('input tokens by default') and the meaning of task, adding little beyond the schema, which is the expected baseline-3 situation.

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 names a specific verb+resource ('cheapest MODELS') scoped by a job/task, and adds a deduplication rule ('each model counted once at its own lowest current price') that separates it from a raw price listing. It does not explicitly differentiate itself from close siblings like cheapest, dearest_models, or cheapest_for_workload, so it falls short of 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?

There is no explicit when-to-use or when-not-to-use guidance, and no sibling is named as an alternative. The phrase 'for a job (task)' implies a task-based lookup scenario, but the reader must infer when to pick this over cheapest_for_workload or search_offers.

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?

With readOnlyHint already covering the safety profile, the description still adds real behavioral detail: the full field-by-field comparison applies only 'for up to 4' models, and the payload includes winners, percentages, 'providers selling all', and summary sentences. The exact behavior at 5 models is left ambiguous (partial comparison is implied but not stated), keeping 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?

It is a single front-loaded sentence that leads with the core action and the model-count constraint before enumerating outputs, with no filler. The long parenthetical list of compared fields makes it dense and harder to parse, but each clause carries information.

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?

There is no output schema, so the description must carry the return-value burden, and it does so thoroughly: per-model best offer, per-field lowest/median prices, context, max output, providers, regions, the 1M-in/200k-out workload cost, winners by percent, and summary sentences. The only gap is the unexplained partial behavior when 5 models are supplied.

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 the sole parameter's min/max items and id-vs-name flexibility are already documented in the schema; the description's '2 to 5 models' merely restates the schema bounds. It adds no extra meaning about id formats, ambiguity handling on name search, or duplicate ids.

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 a specific verb-and-resource phrase ('2 to 5 models side by side') and then enumerates exactly what is compared, so an agent can see this is a multi-model comparison tool rather than a listing tool. It does not name any sibling (e.g. cheapest_models, get_model_prices) to reinforce the distinction, so it stops short of 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 '2 to 5 models' framing implies when the tool is appropriate (a small handful of models to compare), but there is no explicit when-to-use guidance and no exclusion pointing to alternatives like get_model_prices or cheapest_models for single-model or list-style queries. Usage is inferable rather than stated.

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=true, so the safety profile is covered. The description adds genuinely non-obvious behavior: deduplication per model, ranking by each model's own lowest current price, and descending order — details an agent could not infer from the name.

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?

A single front-loaded sentence that gives the result shape, the counting rule, and the ordering with no filler. Nothing could be removed without losing information.

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 ranking tool with full schema coverage and no output schema, the description covers purpose, counting semantics, and ordering adequately. It leaves return-value structure and tie-breaking unstated, which is acceptable given the simplicity but not exhaustive.

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 all four parameters are already documented, which sets the baseline at 3. The description adds no parameter detail of its own; 'Same arguments as cheapest_models' offloads semantics to another tool rather than adding meaning here.

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+resource+ordering: 'the n most expensive MODELS for a job (task)', 'highest first'. It also pins down the counting rule (each model once, at its own lowest current price), so an agent can tell it apart from cheapest_models and median_models without opening either 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 'the top of the market' plus the contrast baked into the name against cheapest_models/median_models makes the use case clear, and 'Same arguments as cheapest_models' points to a comparable tool. It stops short of an explicit when-not or an outright named alternative, so it's a clear context rather than a routing rule.

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?

readOnlyHint=true already covers the safety profile, and the description adds genuinely useful behavior: results are ordered cheapest first, priced in USD, cover every current provider of the model, and account for input, output, cached input tokens and request counts. It does not describe failure behavior (e.g. unknown model names) or result shape in detail, keeping it below 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?

One compact sentence front-loads the outcome (cost of a workload) before qualifying scope and ordering. The trailing gloss '- what the same job costs where' is a redundant flourish that adds no information but is small enough not to be distracting.

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?

With no output schema, the description carries the burden of telling the agent what comes back, and it does: per-provider USD costs sorted cheapest first. For a five-parameter, read-only pricing query this is nearly sufficient; only error/edge-case behavior for ambiguous model names is left unaddressed.

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 of 3 applies; the description's parenthetical restates the workload components (input, output, cached input tokens, requests) but adds no units or semantics beyond what the individual property descriptions already provide. It does clarify that all four are components of a single job rather than independent filters.

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 names a specific resource (cost of a workload for one model across every current provider, in USD, cheapest first) and the scope of the computation is unambiguous. The verb is carried only by the tool name 'estimate_cost' rather than the sentence, and no sibling tool is named for contrast, so it stops short of 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?

Usage is implied rather than stated: 'at every current provider of one model' suggests the cross-provider, single-model scenario, which implicitly distinguishes it from compare_models, but the description never says when to prefer this over cheapest_for_workload or get_model_prices. No explicit when-not conditions are given.

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=true, so safety is covered. The description adds genuine context beyond that: the returned payload includes a citation, and lookups work "for every seller, a hidden test seller too," which signals id coverage. It does not say what happens with a malformed or unknown card_id, nor what a card actually contains, so it is additive but not rich.

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 whole definition is three dense sentences with no filler, and each clause (format, examples, provenance, coverage) carries information. Slightly front-loading the purpose before the ID grammar would improve scannability, but nothing is wasted.

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 single-parameter read-only lookup with no output schema, the highest-risk failure mode is a wrong id format, and that is exhaustively covered. The gap is the return shape — "one card with its citation" does not enumerate card fields — but with no output schema the omission is minor at this complexity.

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?

Although the schema already documents card_id at 100% coverage, the description goes well beyond it: it spells out the three id grammars with concrete worked examples (offer:anthropic|claude-opus-4, model:anthropic/claude-opus-4, seller:anthropic) and states where valid ids originate. This is exactly the extra meaning the schema alone does not supply.

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?

"One card with its citation" states the resource and the return payload, and the surrounding ID-format text makes clear this is a single-item lookup keyed by card_id. It is distinguishable from search_offers (which produces the ids) and from the pricing siblings, though the phrasing is a noun fragment rather than an explicit verb+resource statement.

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 explicitly routes the agent: ids "come from search_offers (offer_id, model_id, provider_id) and from the card_url of every result," which tells the agent this is the follow-up call after a search. There is no explicit when-not guidance (e.g. don't use for bulk lookups, use search_offers instead), so it falls short of a 5.

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?

readOnlyHint=true already declares this is a safe read, so the description only needs to add context. It does add that results span every seller and are sorted by cheapest input price, which is genuinely useful, but it says nothing about result completeness, pagination, or what a seller entry contains.

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?

One sentence, front-loaded with the resource and scope, with the sort order appended compactly. No wasted wording.

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 single-parameter read tool with no output schema, the description covers what is returned (per-seller prices) and how it is ordered, which is enough to call it correctly. Only the sibling disambiguation 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 coverage is 100% for the single 'model' parameter, and the description's parenthetical ('an id, or a name to search for') essentially restates the schema text. Baseline 3 is appropriate since the schema carries the parameter burden.

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 and resource — current prices of one model across every seller — and adds the ordering ('cheapest input first'). It does not distinguish itself from closely related siblings such as 'cheapest', 'cheapest_models', or 'compare_models', so the agent must infer the boundary.

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 explicit when-to-use or when-not-to-use guidance and no alternative is named, despite several siblings (cheapest, cheapest_models, compare_models, dearest_models) that plausibly overlap. Usage is only implied by the phrase 'one model'.

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 readOnlyHint=true, the description discloses that results are ordered newest first and include links, both useful for interpreting and presenting the listing. It leaves result limits, pagination, and whether entries contain summaries or full article text unspecified.

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?

A single compact sentence front-loads the resource and subject, then efficiently adds ordering, links, and intended use. The parenthetical topic list is dense but informative, and there is no filler or repetition of schema details.

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 read-only tool with one optional, fully documented parameter, the description supplies the source, subject matter, ordering, link availability, and a practical use case. Because there is no output schema, the lack of result-cardinality and article-entry field details prevents full completeness.

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 fully documents the sole optional lang parameter, including its allowed values and default of en. The description adds no further language-selection semantics, so the high schema coverage appropriately establishes the baseline score.

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 clearly identifies the resource as AI Rate Card articles about AI model prices, including cheapest models by task, price moves, and costs. The focus on linked articles broadly distinguishes it from the pricing-oriented siblings, though it does not explicitly contrast article retrieval with any particular sibling.

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 'to quote or point a reader to' provides a concrete use case: finding citable or shareable articles. It does not explain when to use a sibling such as get_model_prices or cheapest_models instead for direct pricing data, but the intended context is clear.

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?

readOnlyHint already tells the agent this is a safe read, so the description's burden is lighter, and it does add the return shape: a median price plus the n closest models, which the agent would not otherwise know since there is no output schema. It does not discuss tie-breaking, ordering of the nearest-n list, or whether prices are normalized across scopes, but those are secondary for an aggregation read.

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 compact clauses, front-loaded with the definition before the gloss. Nothing is redundant, though the trailing cross-reference to cheapest_models is a dangling pointer that only helps if the agent already knows that sibling's signature.

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 aggregation tool with a fully documented four-parameter schema, this is sufficient: purpose, result composition, and parameter delegation are all covered. No output schema exists, and the description compensates by naming the returned median and nearest-n models.

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%, with both enums and the component/n defaults documented inline, so the schema carries parameter meaning. The description adds only the delegation 'Same arguments as cheapest_models', which actually forces the agent to consult another tool rather than adding semantics here. 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?

States a specific computation on a specific resource: the median current price of a job across models, plus the n models nearest it. The parenthetical '(task)' and the closing 'what a normal price for this job is' make the resource unambiguous, and the contrast with 'cheapest' is implicit in the sibling name it cites. It falls short of a 5 only because it never explicitly says how it differs from dearest_models or cheapest_models beyond the word 'median'.

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 'what a normal price for this job is' implies the use case (establishing a typical/market price rather than a floor), and citing 'Same arguments as cheapest_models' points to a related tool. However, there is no explicit when-to-use versus cheapest_models/dearest_models, no stated exclusions, and no guidance on when the median is preferable to a min or range query.

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 readOnlyHint=true, the description discloses a non-obvious ordering trait: "priced offers first, doubtful prices after sane ones," which tells the agent that low-confidence prices are demoted rather than hidden. With no output schema, it also enumerates the returned row fields (offer_id, model_id, provider_id, USD per 1M tokens, card_url, cite line). It omits pagination/truncation behavior beyond the 50-row cap, keeping it short of 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?

Front-loaded with purpose and the offer definition, then a compact row-shape clause, then a terse "Next:" routing chain. Dense but every clause carries information; the routing list is the only part that runs long.

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 9-parameter, zero-required search tool with no output schema, the description covers purpose, default-adjacent ordering behavior, return fields, and next-step tools. The gap is mostly in result-shaping details (truncation, how ties or price_status are surfaced), which an agent could still want.

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 explains sort, limit, query, category, free_only, min_context, input_modality, and max_input_price. The description only restates the search axes at a high level and adds the price-unit caveat ("per 1M tokens (or per unit)"), so it meets the baseline without much extra meaning.

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 ("Search current AI model offers") and disambiguates the unit of the resource explicitly: "one model at one provider = one offer." It also names the dimensions you can search by (words, model type, limits), so an agent knows the scope 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?

Explicitly routes the agent onward: get_card with "offer:<offer_id>" for one offer, get_model_prices for one model everywhere, estimate_cost / cheapest_for_workload for a cost. Each named sibling has a stated condition that selects it, which is exactly the when-to-use guidance this dimension rewards.

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 declare readOnlyHint=true, and the description adds substantial context beyond that: it is a non-mutating pre-publication check, requires no account, and exposes the retry loop ('fix each and call again'). It also enumerates the shape of the problems returned (file, line, model, path, value, code, message, hint) plus next_action, which is exactly what an agent needs to act on failures.

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 action and stays to a single dense paragraph with no filler sentences. The cramming of return-field lists, templates, and URLs into one block makes it slightly hard to scan, but nothing is wasted.

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?

There is no output schema, so the description carries the return contract and does so thoroughly (ok flag, structured problems, catalog preview, next_action). It also points to concrete templates, leaving no major gap for a three-parameter validation 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?

Schema coverage is 100%, so the baseline is 3, and the description earns more by clarifying that `models` accepts YAML or equivalent JSON text and that `domain` sharpens the model_page checks rather than being required. It adds real meaning beyond the terse schema strings.

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 object ('check a models.yaml') and scopes it to a provider joining the catalog, which no sibling tool covers. It also anchors the tool to known equivalents (the wizard and POST /v1/provider/validate), so an agent can place it precisely 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?

Gives explicit sequencing ('Call it before provider_publish') and a prerequisite note ('no account needed'). It names equivalent alternatives rather than contrasting when to prefer this one, so it stops short of full when/when-not 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?

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful behavioral context by disclosing the returned fields: name, job type, monthly tokens, context requirement, and model type. It does not explain ordering or pagination, but for a zero-parameter preset list that is a minor gap.

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 definition is a single front-loaded sentence with no redundant wording. The colon-separated field list efficiently communicates the shape of each preset.

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 zero-parameter read-only tool with no output schema, the description does a good job compensating by listing the fields an agent will receive. It is nearly complete, though it could clarify whether the preset list is static or exhaustive.

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?

There are no input parameters, so the schema baseline is 4. The description does not need to explain parameter semantics and appropriately focuses on the returned workload attributes instead.

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 identifies a specific resource: ready-made workloads used by cheapest_for_workload, and enumerates the fields it contains. It is clear enough to distinguish the tool from generic model pricing siblings, though it lacks an explicit verb such as 'list' or 'return'.

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 mention of cheapest_for_workload implies that these presets are related to that sibling tool, but it does not explicitly say when to call workload_presets instead of cheapest_for_workload. Usage is inferable rather than stated.

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