ModelSpec

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

With no annotations, the description carries the full burden and does so: it discloses auth requirements (Bearer API key), cost (2 credits, $0.0053–$0.02 per credit with a pricing link), the proxied endpoint and payload shape, a 16 KB size cap, caller-order preservation, and that unknown fields remain null.

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, then verification details in a tight sequence. Every sentence carries information; the pricing URL parenthetical is the only slightly expendable element, but it supports the stated credit cost.

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?

No output schema exists, yet the description explains the return shape (sourced snapshot facts, offerings, evidence, caller order, null for unknowns) plus auth, cost, and payload limits. An agent has everything needed to invoke and interpret results 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 parameter is already documented; the description adds the wire-level constraint ('{models: [...]} at most 16 KB') and repeats the 2–4 count and caller-order semantics. The byte cap is genuine added value beyond the schema, though most content duplicates structured fields.

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 ('What facts do 2 to 4 named models have?') and immediately delimits scope with 'doesn't choose a model and does not rank', separating it from siblings like decide, rank, and model_info. An agent can select it correctly 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?

The negative framing ('doesn't choose a model and does not rank') gives clear when-not guidance against competing siblings, and the fact-fetching framing implies when to use it. It stops short of naming which sibling to use instead for ranking or selection decisions.

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 no annotations, the description carries the full burden and delivers: auth (Bearer key), cost (1–2 credits, $0.0053–$0.02/credit), endpoint, a 16 KB response bound, trim/oversize behavior, retry semantics, and null-cost semantics ('A null cost is unknown... never show it as $0.00'). It also discloses failure modes (null answer, tied answer, partial status) and what a rejected call does to prior requirements.

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 purpose is front-loaded in one sentence, but the remainder is a wall of ~500 words of output-formatting and prompting policy that reads like a system prompt pasted into a tool description. Rules repeat ('Never add benchmark figures', 'Never claim a rank the response does not show', the $0.00 warning) and an inline worked example ('Right report... Wrong: ...') bloats it further.

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 high-complexity decision engine with no output schema, the description is unusually complete: it outlines the response shape, explain modes and their defaults, size limits and trimming, citation and evidence rules, and null/unresolved semantics. Nothing an agent needs to interpret a call result appears absent.

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?

At 100% schema coverage the baseline is 3, but the description adds real meaning beyond the schema: task_tokens should be sized from the user's own task and the assumption stated, template weights are examples not requirements, 'Complete rows need fields:null', and default behavior for explain/limit/fields. It also asserts 'task free text is rejected; where is an array', which sits uneasily beside the schema's string|null type for `task` — a discrepancy worth resolving.

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 clear question framing the job ('Which models fit this job?') and enumerates what comes back (answer, ranked results, may_qualify, reading, recovery hints, decision_id, snapshot), so the resource and output are identifiable. It differentiates itself from a request-level router, but never names any of the actual siblings (rank, compare_models, hardware_fit, policy_check), so sibling selection still requires inference.

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 invocation policy: 'Call decide early', 'call once per job or role, not per request', 'One vocabulary lookup per unknown facet, then decide', 'Read `next` before another call'. It also states a negative ('Not a router'), but it never names an alternative sibling tool or the condition that would select one, so routing among peers is left implicit.

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 no annotations, the description carries the full burden and does meaningfully: it discloses cost/auth behavior ('Free, no key, and no Authorization header is forwarded'), a storage/privacy constraint ('Storage stays off until covered by the privacy statement'), and the proxy target endpoint. Content restrictions on the note are also stated. It is stronger than typical for an unannotated tool.

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 short and front-loads the guiding question, but the body is a run of telegraphic fragments ('Free, no key, and no Authorization header is forwarded. No prompts, keys or personal details in note; no questions or support.') that is denser than it needs to be and harder to parse than plain sentences.

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 stating the return value ('recorded/not_recorded') plus auth, privacy, and routing behavior. For a feedback/submission tool this covers what an agent needs to call it correctly; only minor detail 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 is already documented in the schema, giving a baseline of 3. The description reiterates the decision_id and note constraints but adds no new syntax or format detail beyond what the schema 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?

The description identifies a distinct job: recording a reliability rating for a prior answer ('Was an answer reliable? ... Returns recorded/not_recorded for a rating after acting'). It is clearly different from siblings like decide, rank, or policy_check, and states the return value. The phrasing is choppy, but the verb+resource is identifiable.

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 timing context ('after acting') and an explicit exclusion ('no questions or support'), which tells the agent when this tool is and isn't appropriate. It doesn't name an alternative sibling, but the siblings are unrelated capabilities rather than competing paths, so this is close to sufficient.

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 no annotations, the description carries the full behavioral burden and does well: it discloses auth requirements (Bearer key), per-call cost and pricing range, the return categories, and the key caveat that estimates can never prove fit. It even states the underlying endpoint being proxied. It stops short of describing rate limits or failure behavior, but the disclosure is unusually strong for an unannotated tool.

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 purpose is front-loaded and there is little outright filler, but the middle sentences are terse to the point of opacity ('Uses basis full with sourced headroom'), and the pricing/endpoint/auth material is packed densely into the same block. It is compact yet sacrifices 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?

With no output schema, the description properly explains the returned verdict types (measured/estimated/undetermined), and it covers auth and cost. But for an 8-parameter tool with 0 required fields, it leaves most input semantics unexplained in both description and schema, which is the main completeness gap.

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 only 13% (essentially just 'memory'), and seven of eight parameters (sku, model, context, runtime, device_count, quantisation, batch) are undocumented in both schema and description. The description adds only 'Memory is decimal GB per device, never pooled,' which is a modest clarification beyond the schema's own text and does not compensate for the wide coverage gap.

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 clear question ('Does this workload fit?') and enumerates the three verdicts it returns (measured/estimated/undetermined), which communicates both verb-adjacent intent and scope. It differentiates from siblings indirectly with 'It doesn't choose a model,' steering the agent away from decide/rank/compare_models, though it never names those 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?

It provides conditional guidance ('basis lower_bound for unlikely only', 'Missing headroom cannot establish likely'), which implies when certain bases are appropriate. However, it never states when to choose this tool over policy_check, decide, or rank, nor what inputs are required versus optional, leaving routing 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 no annotations, the description carries full behavioral burden. It does disclose two useful traits — an API key is required and the return is a specific JSON endpoint (profiles.json) — but says nothing about caching, rate limits, error behavior, or the return shape beyond the endpoint 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?

Three short sentences with no filler, and the resource scope is front-loaded. The question phrasing is slightly awkward and the sentences are a bit disjointed, 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 zero-parameter read tool this covers the essentials: what the resource is, the API-key requirement, and an alternative for decisions. Without an output schema or annotations, it could say more about the returned fields (evidence floors, neutrality commitment are named but unexplained), and the name/content mismatch leaves residual ambiguity.

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 tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline for a parameterless tool 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 names the resource being listed (legacy profiles and ranking rules) and the concrete artifact returned (profiles.json with evidence floors and the neutrality commitment). However, the question format is indirect and the tool name 'list_use_cases' does not obviously map to 'profiles and ranking rules', so an agent must infer the connection.

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 decide for decisions' explicitly routes the agent to one sibling for the decision-making case, which is useful. But there is no broader when-to-use guidance, no statement of when-not-to-use or of how it relates to the similar-looking 'rank' sibling, leaving the usage boundary mostly implied.

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 no annotations, the description carries the full burden and does disclose meaningful traits: the exact endpoint hit, that an API key is required, and that a 'split mode' narrows the response to the display name. It omits rate limits, failure behavior, and how 'split mode' is selected — notably that mode does not appear anywhere in the input schema, so an agent cannot actually request it.

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 with no filler, and the endpoint plus the 'not this / use decide' routing are front-loaded after a brief framing question. The rhetorical opening costs a little density but sets context cheaply.

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 one-parameter lookup with no annotations and no output schema, the description covers the essentials: where the data comes from, that auth is needed, and roughly what comes back. The unexplained 'split mode' is the one dangling thread an agent cannot act on.

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 is documented in the schema ('Catalogue id, e.g. openai/gpt-5-6'), so the description adds little beyond restating it inside the URL template. Baseline 3 is appropriate when the schema already does the work.

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 opening question is a soft framing, but the following sentence makes the operation concrete: it reads a single model's card from https://modelspec.dev/api/models/<model_id>.json. It also distinguishes itself from one sibling ('Not current evidence or a ranking; use decide'), though it does not differentiate against rank, compare_models, or hardware_fit.

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 an explicit when-not ('Not current evidence or a ranking') and names the alternative to use instead ('use decide'), which is a real routing instruction. It stops short of stating the positive case ('use this when you want the static card for one model'), leaving the trigger condition implicit.

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 no annotations, the description carries the full burden and does substantial work: it discloses the auth requirement (API key, Authorization: Bearer), the cost model (5 credits/call, $0.0053–$0.02 per credit), and the proxied POST endpoint. It also clarifies a subtle semantic ('undetermined is not a pass'). It omits rate limits, error/retry behavior, and pagination semantics.

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 core question and return shape, then auth, cost, endpoint and the sibling alternative. Dense and nearly every sentence earns its place, though the pricing URL and proxy detail make it slightly cluttered.

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 tool with nested objects and no output schema, it covers auth, cost, endpoint and verdict semantics well, and describes the per-model/per-platform return shape. It leaves the paging/filter parameters and the policy sub-fields (residency, commercial_use) unexplained, so an agent would still have to guess at several arguments.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% across 7 parameters, one of which is a nested policy object, so the description must compensate and largely does not. It indirectly explains the verdict vocabulary ('pass, fail or undetermined', matching the verdicts enum) and names the licence/origin dimensions of the policy object, but limit, offset, require_no_undetermined, models and platforms are never explained.

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 opening question plus the explicit statement of what is returned ('pass, fail or undetermined per model/platform for licence, origin and data handling') gives a specific verb+resource and scope. It also differentiates itself from the sibling 'decide' by stating 'It doesn't choose a model'.

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 names an alternative tool and the condition that selects it ('use decide among passing rows'), which is real routing guidance. It does not, however, explain when to apply the filter parameters (models, platforms, verdicts) or when other siblings such as compare_models or rank would be more appropriate.

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 no annotations, the description carries the full burden and does so well: it discloses deprecation/lag risk ('scores lag the catalogue and newer models may be unranked'), auth requirements ('Authorization: Bearer'), cost per call and credit pricing, and output semantics (shortlist vs verdict). It stops short of stating pagination/error behavior, keeping it below a perfect score.

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 deprecation warning and the 'use decide' routing are correctly front-loaded, and each sentence carries distinct information (routing, output caveats, auth, cost, presentation rules). It is dense and slightly sprawling across concerns, but no sentence is pure 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 deprecated, paid tool with no output schema, the description covers the return shape, safety/routing rules, and user-presentation obligations well. The remaining gap is the undocumented nested parameters, which is captured under parameter semantics rather than a missing description of the tool's 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 description coverage is only 25%, so the description must compensate, but it never explains the parameters. The nested 'constraints' and 'environment' objects and 'limit' are undocumented in both schema and description, and only 'use_case' is even implicitly referenced via 'fixed use-case profile'.

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 (a ranking of models against a fixed use-case profile) and qualifies the output ('a shortlist with evidence_basis and input provenance, not a quality verdict'). It distinguishes itself from siblings by leading with 'Legacy v1; use decide' and explaining the fixed-benchmark scope, so an agent can tell it apart from decide and compare_models 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?

It gives explicit when-nots ('Don't call it as a fallback when decide has no single leader; report its tie') and names the preferred alternative (decide) by name. It also routes downstream behavior ('When next_move is present, offer it instead of a pick'), leaving little 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 no annotations, the description carries the full burden and does disclose meaningful traits: an API key is required, compact pages cap at 20 rows with no counts, empty pages terminate results, search ranks all tokens before subsets, misses return nearest ids, and split-mode full details exclude model facts and counts. It omits error/rate-limit behavior, but the coverage is unusually rich for an unannotated tool.

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?

Nine fragmentary sentences are strung together with undefined jargon ('Spec', 'unknown facet', 'split-mode') and no front-loaded statement of what the tool is. The opening sentence is a rhetorical question that delays rather than delivers the purpose, so much of the prose does not earn its place.

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 tool with no annotations and no output schema, the description should describe the return shape, but it only says 'Returns ids and task types' and notes counts are omitted. Behavioral details are comparatively complete, yet the actual response structure an agent needs is left unclear.

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; the baseline is 3. The description adds marginal semantic nuance (paging applies to cross-section lookups, search ranking order, split-mode exclusions) but no syntax or format detail beyond what the schema 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?

The description opens with the vague rhetorical 'What can a Spec say?' and only states 'Returns ids and task types', which is narrower than the 14 sections the schema exposes (models, providers, benchmarks, etc.). It implies a vocabulary-lookup resource but never names a clear verb+resource and does not distinguish itself from siblings like model_info or list_use_cases.

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 concrete routing advice: 'One vocabulary lookup per unknown facet, then decide' and 'Use decide to compare models', naming the alternative sibling for a specific task. It stops short of explicitly stating when not to use it or how it relates to the other seven siblings.

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