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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context by explaining that 'pay' switches the meaning of the numbers between dollars and plan consumption, and that a per-model breakeven token share is returned. It does not say what happens when a supplied model name is unknown or unpriced (there is a not_yet_priced sibling), which is the main remaining 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?

Two sentences, front-loaded with the compare action and the returned fields, then the routing rules. The first sentence is long and comma-heavy but every clause carries information; there is 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?

With an output schema present the description need not restate return values, and annotations cover the read-only/idempotent profile, so the description's job is mainly routing and it does that well. The only shortfall is guidance on unpriced or unrecognized model names, which matters given a sizable model-name surface.

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 every parameter including the pay enum and the answer_tokens-per-model map is already documented. The description adds the 2-6 model bound and the dollars-vs-plan distinction, but this largely restates 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 verb (compare) and resource (models), bounds the scope to 2-6 named models, and enumerates the outputs the agent will get back: rating, prices, cost per task, the pick, and each model's breakeven token share. This is clearly separable from every sibling at a glance.

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 inclusion condition ('when the user already has candidate models in mind') and then names three exclusions with the sibling that handles each: find_models for discovering candidates, suggest_for_project for inferring work from a prompt, estimate_cost for monthly budget. 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 already declare readOnlyHint, idempotentHint, and openWorldHint=false, so safety and determinism are covered. The description adds real context beyond them: pricing uses each model's cheapest listing and reports cache savings, which an agent needs to interpret results. It stops short of noting what happens to models lacking a listing, which is a minor gap given a sibling named not_yet_priced.

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 action and output shape, followed by usage routing. Every clause carries information; no padding or repeated name/title text.

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 an output schema present, the description needn't detail return values, and its output summary plus usage routing is sufficient to call the tool correctly. The only omission is behavior for models without a price listing, a small but real gap for a pricing 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 description coverage is 100%, so all six parameters including cached_tokens and cache_write_tokens are already documented in the schema. The description only restates that token counts and daily call volume are inputs, adding no syntax, units, or edge-case guidance beyond the structured fields. 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?

States a specific verb (price) and resource (a workload across 1–10 models), and specifies the outputs returned: dollars per call, per day, per 30 days, plus cache savings. The scope (cheapest listing per model) makes it clearly distinct from compare_models and price_my_usage.

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 ('when the question is a budget or a bill: token counts and calls a day are known') and names two alternatives with the conditions that select them, compare_models for quality decisions and price_my_usage for export-based pricing. 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 already declare this is a read-only, idempotent, closed-world operation, so the description does not need to restate safety. It adds useful behavioral context by disclosing that estimates come from the user's own logged timed runs and that the tool reports when none exist. The main remaining gap is output-shape detail, though an output schema exists.

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 compact sentences with the core purpose and data source up front, followed by usage conditions and exclusions. Every sentence carries useful routing or behavioral 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 seven-parameter estimator with an output schema and strong annotations, the description supplies the key missing context: where timing data comes from, the precondition that runs must be logged, and which sibling tools handle adjacent cases. Nothing an agent needs in order to choose and 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 description coverage is 100%, so the schema already documents all seven parameters including enums, defaults, and token semantics. The description adds context about the overall estimate but does not contribute parameter-level meaning beyond what is already structured.

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 outcome: estimating duration for one call and a whole job, reported as usual time and a slow day. It names the data source (the user's own timed runs kept by log_run) and explicitly distinguishes itself from estimate_cost and forecast_job.

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 says to use it when the question is time rather than money and when some runs have been logged. It names both alternatives and the conditions that select them: estimate_cost for cost questions and forecast_job when a promptfoo sample exists.

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, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds useful behavioral context: browsing returns highest-rated models at their cheapest listing with ratings, while passing `name` switches to a lookup that lists every host offering that model. It does not add much beyond that, but with annotations and an output schema present, this is appropriately informative.

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 front-loaded with the primary behavior, then usage guidance, then exclusions. Every sentence earns its place, and there is no redundant 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 7-parameter read-only catalogue tool with a complete input schema, output schema, and explicit annotations, the description gives enough about modes, filters, and alternatives for an agent to call it correctly. Return-value details are correctly left to the output 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 100%, so all seven parameters are already documented in the input schema. The description reinforces the key filters (price, prompt size, ability, maker limits, and `name` mode) but does not add syntax or edge-case semantics beyond what the schema provides; 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 and resource: list/filter models, or look up one model by name and list every host offering it. It clearly distinguishes the browse mode from the name-lookup mode, so an agent can tell what the tool does 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 explicitly says to use this when browsing or filtering the catalogue, or to find a model's exact name. It also names alternatives and exclusions: compare_models for choosing between named models, suggest_for_project for a prompt in hand, and estimate_cost for a budget.

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 and openWorldHint=false, so safety is covered. The description adds genuine estimation semantics beyond that (that cost is reported at the cheapest listing next to the listing the sample used, that accuracy carries a 95% range, that break-even is computed against the pick), which tells the agent how to interpret the numbers. It stops short of stating assumptions or limits on the extrapolation, so not 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?

The lead clause front-loads the action and resource, and the trailing sentences carry routing information rather than filler. It is dense and slightly run-on in the output enumeration, but nearly every clause earns its place by naming a distinct reported metric.

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 already defines return values, annotations cover the safety profile, and schema coverage is 100%, so the description only needs to convey purpose, preconditions and sibling routing — all of which it does. Nothing an agent needs to select or invoke this 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%, so every parameter (way, thinking, concurrency, wrong_answer_cost, items, promptfoo_results) is already documented in the schema, setting the baseline at 3. The description references the sample and the whole job's size but adds no format or defaulting nuance beyond the schema text.

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 (estimate) and resource (a whole job's time, cost and accuracy) and enumerates exactly which outputs are produced: usual/slow-day time, cheapest-vs-used listing cost, 90-day price-change chance, accuracy range and break-even. It also distinguishes itself from the similar-sounding siblings by requiring a promptfoo sample, so an agent can separate it from estimate_cost/estimate_time without opening a 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?

Explicit precondition: 'Use when a promptfoo results file of a sample exists and the whole job's size is known.' Explicit exclusion plus named alternatives: 'Not for a job with no sample (estimate_cost for money, estimate_time for time).' Both the when and the when-not, with the correct fallback tools, are stated outright.

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 the safety profile (readOnlyHint, idempotentHint, openWorldHint=false), and the description adds real context beyond them: the tool depends on prior log_run measurements and pulls electricity cost from EIA or a user-supplied rate. It does not discuss sensitivity of the break-even result or how load feasibility is judged, which keeps 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?

Three sentences, front-loaded with the decision the tool answers, then prerequisites, then exclusions. Phrasing like "the cost a month each way" is slightly compressed but no sentence is wasted; structure is sound.

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 13-parameter, 6-required analysis tool with an output schema and full annotations, the description covers purpose, prerequisites, and alternatives adequately. Remaining gaps (result interpretation, what happens with missing run data) are minor given the output schema documents return values.

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 13 parameters are already documented, including the electricity_price default and the state/watts options. The description only reinforces the electricity source and the hardware-price input, adding little beyond the schema; 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?

States a specific comparison verb and both resources: local hardware cost versus per-call cloud cost, plus the derived outputs (break-even month, whether it keeps up with load). It also names the sibling tools it is not, so an agent can separate it from compare_models and estimate_cost without opening a 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?

Explicit use condition ("Use when the question is whether to buy hardware for a local model"), explicit exclusion ("Not for cloud-only comparisons (compare_models or estimate_cost)"), and stated prerequisites (timed runs via log_run, hardware price). 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?

With annotations already declaring non-destructive, local (openWorldHint=false) and non-idempotent, the description adds real value: writes to a file 'on this computer', 'Nothing is sent anywhere' (privacy/data-locality guarantee an agent may need to relay), and 'returns what it stored'. It does not warn that repeated calls append duplicate records despite idempotentHint=false, which is the one consequence an agent would most want spelled out.

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: what it records first, when to use it second, and the non-query/locality caveats last. No filler and no repetition of schema detail.

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?

Output schema exists and annotations cover safety, so the description only needs purpose, trigger and behavioral caveats — all present. The main residual gap is what happens on repeated logging (duplicate records vs. update) and where the file lives, which matters for a stateful writer.

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 every parameter is already documented in the schema, including the promptfoo_results path semantics and the thinking auto-detection. The description only re-lists 'model, tokens, seconds, how it was called' without adding format, precedence, or mutual-exclusion rules between a single run and a results file. 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?

States a specific verb and resource ('Record a timed run') plus the two supported input modes (single run with model/tokens/seconds/way, or a whole promptfoo results file) and the downstream consumer (estimate_time). An agent can distinguish it from estimate_time or forecast_job without inspecting 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?

'Use right after a call or a promptfoo run whose time is known' gives a clear timing condition, and 'Not a query: it stores and returns what it stored' explicitly rules out the wrong usage pattern. It stops short of naming which sibling to call instead when the agent does want a query, so it's a strong 4 rather than 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?

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is covered. The description adds genuine context the annotations cannot: that results include the typical lag between Arena first showing a model and the catalogue pricing it, which shapes how the output should be read. It stops short of describing result ordering or volume, a minor gap given an output schema exists.

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 sentences, all load-bearing, with the definition first and routing second. The opening clause is slightly dense ('models Arena has rated that LiteLLM's catalogue does not price yet') but no sentence 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 optional-parameter read tool with full schema coverage and an output schema, the description covers purpose, routing and the meaning of the returned timing data. The only omission is the behaviour of the default no-maker case.

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 single parameter carries its own description with examples (meta, ibm), so the schema does the heavy lifting. The description implies per-maker aggregation but never says what omitting maker returns (all makers). Baseline 3 is appropriate 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?

Opens with a specific verb and a precisely scoped resource: models Arena has rated that LiteLLM's catalogue does not price yet. It also names the sibling (find_models) that covers the complementary set, so an agent can separate the two without reading 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?

States both triggering conditions (a brand-new model missing from other tools' answers, or asking what is coming) and an explicit exclusion: not for models that already have a price, use find_models. There is essentially nothing left to infer.

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 and openWorldHint=false, so the safety profile is covered and the description instead spends its words on payload content — the historical change records, the sourcing ('LiteLLM change behind it'), and probabilistic 90-day/year forecasts. It omits result size/pagination and how ambiguity between a bare model name and a host-qualified listing is resolved, which keeps 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?

The key scoping and exclusion information is front-loaded and there is no filler; the exclusion clause doubles as routing. The first sentence is a long multi-clause run-on that could be split for faster scanning.

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 an output schema present, return-shape explanation is optional, and the description still summarizes the payload well; usage and alternatives are fully covered. The only residual gap for a 2-param read tool is no note on model-name resolution or empty/missing-history behavior.

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 already carry descriptions, so the schema does the heavy lifting. The description's 'with `date`, the prices on that day' restates what the schema field description already says, adding no new syntax, format, or edge-case guidance.

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?

Names a specific verb and resource ('Show one model's price history') and enumerates exactly what is returned: price/retirement changes since 2023, the LiteLLM change, and forward-looking risk over 90 days and a year. It explicitly contrasts itself with find_models and estimate_cost, so an agent can route 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?

Gives the positive trigger ('one model over time, a past price, or how likely a price is to move') and the exclusion ('Not for today's cheapest price of several models'), naming the two sibling tools that should be used instead. Both sides of the routing decision are covered.

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 read-only and idempotent annotations, the description discloses the data scope ('Reads token counts, names and dates only') and privacy property ('nothing leaves the computer'). It also characterizes the analysis outputs, including per-session historical pricing, cheaper alternatives, a 95% range, and model-comparison significance.

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 front-loaded with the core action, then adds use conditions, exclusions, and privacy context. Despite being a dense paragraph, every clause contributes relevant selection or behavioral information for a complex analysis tool.

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 the presence of an output schema, full input-schema descriptions, and read-only annotations, the description supplies the remaining needed context: what the tool answers, when to choose it, when not to, and its local-only data handling. Nothing material is missing for correct invocation.

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 five parameters are already documented in the input schema. The description adds domain context that inputs can come from a ccusage/codeburn export or token mixes, but it does not add parameter-specific detail for task, limit, or compare beyond 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 states a specific verb and resource: pricing the user's own past coding-agent usage from an export or token-mix list across every rated model. It also explicitly distinguishes this from sibling tools for future workloads (estimate_cost) and prompts (suggest_for_project).

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 gives a clear use condition: when a usage export or token-mix list exists and the question is what the same work would have cost elsewhere. It also names when not to use it, routing the agent to estimate_cost and suggest_for_project.

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 and openWorldHint=false, so safety is covered; the description adds the non-obvious behavior that it infers the type of work from the prompt and that 'best value' is defined by vote-indistinguishability from the top model rather than raw benchmark rank. It does not say how stable/repeatable the suggestion is or how the pay/answer settings change the ranking, which keeps it below 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 the purpose in the first clause, then the usage rule and exclusions; no filler sentences. The parenthetical defining best value is dense and slightly convoluted, which is the only cost to 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?

Since an output schema exists, the description needn't enumerate return values, yet it still names the three recommendation slots and the cost-per-task figure, which is enough for an agent to know what to do with the result. The only gap is not explaining that the pay setting switches the comparison basis between dollars and plan tiers, which affects how results should be interpreted.

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 both enums are documented inline, so the schema carries the parameter burden. The description mentions effort level and cost per task but does not elaborate on how 'pay' (api vs claude vs chatgpt) or 'answer' length shift the recommendation, adding little beyond the schema. 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?

States a specific verb (suggest) and resource (model + effort level for a prompt/project), and explains what the recommendation contains: best value, top rated, cheapest rated, each with cost per task. It explicitly distinguishes itself from siblings compare_models and find_models by name, so an agent can pick it 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?

Gives an explicit trigger ('when the user asks "which model should I use for this" and the work itself is in hand') plus two named exclusions with the conditions that select them (compare_models for named candidates, find_models for browsing by limits). This is the full when/when-not/alternative pattern.

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