FreeToken — LLM API discovery

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds value beyond them by stating the result is an estimate rather than a charge or live quote, and by clarifying the token-unit semantics that would otherwise be misread.

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, zero filler, with the core purpose front-loaded and the unit caveat and negative scoping following in priority order.

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, so the description should ideally state the return shape (currency, whether it itemizes input/output cost). Combined with an unexplained locale parameter and no pointer to where valid priceIds come from, the picture is adequate but not complete.

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 0%, so the description carries the burden. It resolves the most dangerous ambiguity by explaining inputMillion/outputMillion are millions of tokens, not token counts, but it says nothing about locale (which the schema enum ties to shipped locales) or the priceId pattern/'listed' constraint.

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 (Estimate) and resource (USD cost) and bounds the scope to ONE listed priceId with its exact billing scenario. It doesn't name a sibling, but the wording 'one listed priceId' implicitly points at the price-reference listing rather than any of the sibling tools, so an agent can place it without ambiguity.

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 excludes three tempting misuses: live quote, free quota calculation, and charge. That is genuine when-not guidance. It stops short of naming the alternative source for valid priceIds (e.g. list_price_references) or stating prerequisites, so it is strong but not complete.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real value beyond that: it states that only environment variable references are returned and that no keys, prompts, network calls, or file writes occur, which tells the agent exactly what the output does and does not contain.

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, front-loaded with purpose and immediately followed by the output guarantee. The only filler is the trailing compatibility caution, which is vague but cheap.

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 correctly compensates by describing the return content (env var references only, no secrets). It is nearly complete for this tool, missing only an explanation of the format/locale choices.

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

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

Schema description coverage is 0%, so the description has to carry the parameter burden. It meaningfully constrains 'selections' (1–5 exact catalog pairs), but says nothing about the 'format' or 'locale' enums, which are the two parameters an agent most needs to reason about.

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 ('Render') and a specific resource ('keyless config') with an explicit scope (1–5 exact catalog providerSlug/modelSlug pairs). No sibling tool produces config output, so the purpose is unambiguous.

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 only guidance is the vague caution 'Review compatibility before using,' which does not say when to choose this tool, how to pick between the route-pack/litellm/env-template formats, or what 'compatibility' means. No alternatives are named.

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, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description still adds value by clarifying a non-obvious boundary ('No signup or key generation is performed'), which tells the agent this tool never mutates provider/account state. It stops short of describing return shape or rate/limit behavior, but with annotations present that is acceptable.

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 short sentences, front-loaded with the core read action and followed immediately by the negative-scope constraint. Nothing is padded or repeated from the name or schema.

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 burden of explaining what is returned, and it does list the content categories reasonably well. However, with 0% parameter coverage and two undocumented inputs (including an enum-constrained locale), an agent lacks the detail needed to call the tool confidently in edge cases such as invalid provider slugs or non-English locales.

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

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

Schema description coverage is 0%, so neither 'provider' nor 'locale' has any documented meaning anywhere. The description mentions the concept of a 'published provider' but gives no format, no note that provider is a required kebab-case slug, and no hint that locale selects a localized guide — leaving both parameters effectively unexplained.

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 ('Read') and a well-defined resource ('official application links, payment/identity conditions and existing application steps for a published provider'), so the agent knows exactly what is returned. It does not, however, explicitly differentiate itself from siblings like estimate_cost or export_keyless_config, leaving that inference to the agent.

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 only implied: the agent can guess this is the lookup step before applying, and 'No signup or key generation is performed' rules out a credential-creation path. There is no explicit when-to-use guidance, no stated prerequisites, and no named alternative among the sibling tools.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. The description still adds real value beyond them: it clarifies that no new checks are executed and, importantly, that absent or stale evidence must not be read as uptime or outage — a non-obvious interpretation rule an agent would otherwise get wrong.

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?

Four short, front-loaded sentences with no filler. The most consequential constraint (no new checks, don't infer uptime) comes early. Slightly clipped to the point of under-specification, but nothing is redundant.

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 should hint at the shape of what comes back (what fields constitute a sampled check, timestamps, staleness markers) and it does not. It also never says what happens with the default invocation of zero parameters — all routes? a default limit? Adequate, but incomplete for a tool whose whole value is interpreting evidence freshness.

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

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

Schema description coverage is 0%, so the description must carry parameter meaning. It only supplies the slug convention for provider and model; 'limit' is left ambiguous (a limit on what — routes, checks, samples?), and the locale enum's effect on returned evidence is never explained. Two of four parameters remain semantically opaque.

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: it reads existing sampled checks for public catalog routes, rather than computing anything new. That distinguishes it from the action-oriented siblings (estimate_cost, export_keyless_config, search_models). It loses a point because the tool name ('get_route_status') implies a broader status object than what is described, and the description never says what a 'route' is keyed by.

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?

'No new checks run' plus the warning about missing/stale evidence implies the intended use: consult previously collected evidence rather than trigger a live probe. However, no sibling alternative is named for the case where the agent wants a fresh assessment, and there is no statement of when this tool should be skipped.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, so the safety profile is covered. The description adds genuinely new behavioral context: the result set is a curated, dated reference sample rather than exhaustive or live data, which affects how the agent should trust and present results.

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, zero filler, with the core purpose front-loaded and the scope limitation second. Every clause earns 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 one-parameter, read-only list tool with no output schema, the description adequately conveys what is returned conceptually (IDs and scenarios) and sets expectations about coverage. The undocumented locale parameter is the only meaningful 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 0% and the description never mentions the single 'locale' parameter or what it affects. The enum values are self-evident language codes, which is the only reason this is not a 1, but the description does nothing to compensate for the 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?

Specific verb and resource: 'List dated price reference IDs and billing scenarios'. It also names the consuming sibling ('for estimate_cost'), so an agent can distinguish it from search_models or get_provider_guide 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 supplies the key when-not constraint ('not complete market coverage or live quotes'), which tells the agent this is a static lookup rather than a quote source. It stops short of explicitly stating 'call this before estimate_cost', so it is clear context rather than full routing guidance.

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

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

Annotations already cover read-only, idempotent, non-destructive and closed-world, so the description is free to add the genuinely useful caveats: matching is substring-based, results are not a benchmark or a promise of free access, and each hit includes conditions, dates and source links. It omits anything about the limit/pagination behavior, 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?

Two dense sentences with no filler, and the core purpose is front-loaded ahead of the caveat. The trailing list 'conditions, dates and source links' is slightly compressed and cryptic, 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?

With no output schema the description does sketch the return shape (slugs plus conditions, dates, source links), and annotations cover the safety profile. However, for a 7-filter search tool with zero parameter documentation, an agent still lacks guidance on how to compose filters or what limit does.

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, so the description must carry the burden, yet it explains only the implicit substring behavior of the query. limit, locale, minContextTokens, provider and accessType are left entirely to bare type/pattern/enum definitions, and no default or interaction between filters is described.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb and resource: 'Filter the published catalog', and clarifies it is a substring search. It also tells the agent what comes back (exact provider/model slugs), which distinguishes it functionally from cost/route/guide siblings, though it never names a sibling explicitly.

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 only implied — the phrase 'for subsequent tools' suggests it is a lookup step preceding other calls, but there is no explicit 'use this when' or 'do not use this when'. The aside 'not a benchmark or guarantee of free access' guards against misuse of results rather than guiding tool selection.

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