Attic Standard

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

Annotations only cover the safety profile (readOnly/idempotent/non-destructive), and the description goes well beyond them: it discloses the tier gating (free tier returns counts, ranges and redacted samples; PRO key unlocks vendor names, model names and exact prices) and the unit semantics for token vs. non-token modalities. That is exactly the behavioral context an agent cannot get from structured fields.

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 capability statement, then tier/unit semantics, then two compact examples. Every sentence carries information, though the paid-tier pitch sentence is denser than strictly needed for selection.

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-value burden and does so: it names the aggregates (cheapest/dearest offer, vendor count, spread ratio) and the per-offer channel detail, and flags that the free tier redacts them. Nothing material for correct invocation or interpretation 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, but the description adds genuine meaning: it clarifies the model_name vs. model_family distinction via examples, implies the direction dimension (input/output), explains the pricing units (per 1,000 tokens, per image, per second, per minute, per 1,000 characters), and explains what _atom_api_key unlocks. It does not explain limit/pagination behavior 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+resource at a specific scope: pricing one model or a whole family 'across every vendor that sells it', and enumerates the outputs (cheapest/dearest offer, vendor count, spread ratio, per-offer channel). This is readily distinguishable from siblings like get_model_detail, search_models, or list_vendors.

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?

Two concrete natural-language examples map intent to parameters ("Cheapest place to run Llama 3.3 70B" -> model_name=..., "Qwen family output prices" -> model_family + direction), which gives clear context for when to use which parameter. It lacks explicit when-not guidance or naming of an alternative sibling for single-model lookups.

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 establish read-only, idempotent, non-open-world behavior, and the description adds genuine context beyond them: it is free/public tier, prices are per 1,000 tokens with modality-specific units, the May 2026=100 base, coverage/basket-change flagging, and that PRO-level vendor data requires a key. Return-format detail is thorough but pagination/size limits are not mentioned.

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 one-line purpose, then families, then output contents, then examples - a logical order. It is somewhat long but nearly every sentence carries information an agent needs; no filler 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?

With no output schema, the description carries the full burden and discharges it: it explains the benchmark level, spot price (median/p25/p75), the change dimensions, and coverage counts with basket flags. An agent knows what it will receive before calling.

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 adds meaning through worked examples showing accepted code forms ('TXT', 'NCL', 'AIPI TXT GLB') and the category values that drive index_category. It clarifies the free-vs-PRO distinction of _atom_api_key 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?

States a specific verb and resource ('Attic Standard price indexes for AI inference') plus the exact scope ('every published index at the week the site shows'). The six families enumerated make it clearly distinct from siblings like compare_prices or get_kpis, though no sibling is named 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?

The three examples map real user questions to specific parameters ('Where is text inference priced this week?' -> index_code="TXT"), which gives clear context for when to reach for this tool versus the category-wide alternatives. No explicit when-not-to-use or named-alternative guidance is provided.

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, so safety is covered; the description adds value beyond that by disclosing the free-vs-PRO tier split, what data each tier returns, and the freshness window ('this week'). It does not mention pagination, rate limits, or result size limits, 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?

The core purpose is front-loaded in the first sentence, tier behavior follows in one dense sentence, and the examples are compact and directly actionable. No filler 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 no output schema, the description usefully characterizes the return shape (composition broken down by channel, origin, tier, license) and the tier-dependent depth, so an agent knows roughly what comes back. It omits any note on result size or pagination for a potentially large basket listing, which 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 coverage is 100%, so the schema already documents index_code, direction and _atom_api_key; baseline is 3. The description does add meaning for _atom_api_key via the free/PRO tier explanation, but says nothing about the 'direction' enum parameter or index_code syntax beyond what the schema and examples already show.

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 concrete verb+resource ('what sits inside an index basket') and enumerates the returned composition (SKUs, models, vendors, split by channel/origin/tier/license), which makes it clearly distinct from a benchmarks or price-history tool. It stops short of explicitly naming a sibling (e.g. get_index_benchmarks) to route against, so it lands at 4 rather than 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 two worked examples ('What is in the flagship index?' -> index_code="FLG"', 'How much of the China index is sold through neoclouds?' -> index_code="CHN"') give clear situational context for when to reach for this tool. There is no explicit when-not or named alternative, so it is not a full 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 read-only, idempotent, non-destructive, and closed-world behavior. The description adds useful context beyond that: weekly publication, return fields (value, IQR, population, week, month, vs-base changes, definition), and free public access. It does not describe rate limits or pagination, but the added context is substantial.

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 a clear headline, then uses grouped bullets to enumerate the nine KPIs, followed by return details and access tier. Every part serves a purpose, though the list is lengthy; it avoids filler and is well organized.

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 compensates by describing the fields returned for each KPI. Annotations cover safety, and the schema covers parameters. It also notes the free tier versus PRO key, though it does not elaborate on the effect of the 'weeks' parameter beyond the 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 the schema already documents all three parameters, including enum-like values for 'group'. The description lists the three groups, which aligns with the schema but adds no new syntax or meaning beyond what is already provided.

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

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

The description states a specific resource: 'The nine market KPIs Attic Standard publishes each week,' and enumerates them by group. It is clearly distinguishable from generic stats tools by its focus on nine named KPIs, though it does not explicitly name or contrast with siblings like get_market_stats.

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 explicit when-to-use guidance or alternatives are provided. The description implies usage by listing the KPIs and noting the free tier ('fully public'), but an agent must infer that this tool is for retrieving published KPIs rather than, say, market statistics from a sibling tool.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely non-obvious behavior: free tier returns counts, ranges and redacted samples while PRO returns vendor/model names and exact prices, and tokens are priced per 1,000 tokens while other modalities use their own units. That is real value beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with what the tool returns and then the tier/unit rules. The pricing parenthetical and URL are mildly promotional but do convey the gating condition an agent must know, so they largely earn their 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?

No output schema exists, so the description must carry return-value semantics, and it does: counts/ranges/redacted samples vs vendor names and exact prices, plus unit definitions. The one gap is that it does not clarify the shape of the distributions (percentiles vs min/max), but for a relatively simple two-parameter tool this is close to sufficient.

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 modality and _atom_api_key are already documented, making 3 the baseline. The description goes further by explaining the unit convention that governs the numbers returned for each modality (per image, per second, per 1,000 characters), which the schema does not convey.

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 ('tracked market') and enumerates what it covers (vendors by channel, countries, models, priced SKUs, indexes) plus price distributions by modality/unit/direction. That is far more specific than a tautology, but it never names a sibling tool, so it does not explicitly differentiate itself from compare_prices or get_kpis.

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 implies the tool is the aggregate market-overview endpoint ('coverage of the tracked market'), and it usefully explains the free vs PRO tier condition. However, it never says when to pick this over get_kpis, get_vendor_catalog or compare_prices, so routing guidance is implicit 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower, and the description adds meaningful behavioral context: the free tier returns counts, ranges and redacted samples, while PRO unlocks vendor names, model names and exact prices. This tells the agent upfront that a free-tier call may not return the identifiers it needs, which is genuinely actionable. It stops short of covering lookup-failure behavior or response shape details.

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 substantive content list and followed by the access-tier caveat. It is efficient, though the parenthetical price and URL read as promotional padding rather than tool guidance.

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 return-value burden and does so by enumerating returned fields and the tier-based redaction. Combined with the annotations covering safety and idempotency, an agent has enough to invoke it correctly; only error/not-found behavior is 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 description coverage is 100%, so both parameters (model_name with examples, _atom_api_key with its tier purpose) are already documented. The description's tier explanation for the key restates what the schema says, adding no syntax or format detail beyond it. 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 names a specific resource ('One model in depth') and enumerates exactly what is returned: specs (creator, origin, tier, license, context window, output limit, training cutoff, modalities), index memberships, and per-vendor pricing. This level of content specification makes it distinguishable from a bare lookup tool even without naming siblings 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?

The description implies the usage context (look up a single known model for detailed specs and pricing) and explains the free vs PRO access condition, but never states when to prefer this over siblings such as get_model_intelligence, search_models, or compare_prices. Usage is inferable rather than instructed.

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 genuinely new operational context: the call is fully public and free, requires no key, and returns the same figures published on atticstandard.com. That auth/tier disclosure is exactly the kind of context annotations cannot convey.

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 deliverable and its six components, then the value framing. No filler. It is dense with internal jargon ('frontier context ceiling', 'training cutoff lag'), but each clause earns its place by defining the payload.

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 takes on the burden of explaining what comes back, and it does so by enumerating all six measures. Zero required parameters, read-only annotations, and a stated free tier leave nothing an agent needs missing before invoking it.

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

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

There is one optional parameter with 100% schema description coverage, so the schema already explains _atom_api_key and its free-tier omission. The description corroborates the free/public nature but adds no syntax or format detail beyond the schema. Baseline 4 applies when the schema carries the parameter semantics and the parameter is optional.

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 precisely: six enumerated capability/coverage measures (reasoning tier share, long-context saturation, frontier ceiling, output ceiling spread, training cutoff lag, vendor modality breadth). That is specific enough for an agent to know what it gets. It only gestures at sibling differentiation by referencing 'the market KPIs' rather than naming get_kpis or get_model_detail, 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?

It gives interpretive context ('read alongside the market KPIs, they explain why models are priced the way they are'), which implies a use case. However it never states when to prefer this over get_kpis, get_market_stats, or get_model_detail, and offers no exclusions or prerequisites. Usage is implied, not directed.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description adds genuinely new behavioral context: free vs 'Attic Standard MCP PRO' tier gating, the 260-week cap, and the unit convention ('per 1,000 tokens; other modalities use their own unit'). That is useful beyond the annotations, though it still doesn't describe pagination or ordering.

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 two modes, then the unit caveat, then examples – a sensible priority order with no filler sentences. It runs slightly long with the examples, but every part is load-bearing for correct invocation.

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 return-shape burden and does so: index mode returns benchmark level, May 2026 = 100, and spot price with 25th/75th percentiles; model mode returns per-vendor weekly prices and repricing events. Combined with the tier and unit notes, an agent has everything needed to call it correctly.

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

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

Schema description coverage is 100%, so the baseline is 3, but the description adds real semantic value: it explains that index_code is free while model_name and vendor are PRO, and clarifies that vendor only applies 'with model_name'. The per-token/per-unit note further disambiguates the prices being returned.

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?

It names a specific verb and resource ('Weekly history') and splits the tool into two clearly scoped modes driven by index_code vs model_name, so the agent knows exactly what gets returned in each case. It does not, however, explicitly contrast itself with siblings like compare_prices or get_index_benchmarks, which is what separates a 5 from a 4.

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 two worked examples ('How has the neocloud index moved since May?' -> index_code='NCL'; 'Has anyone cut the price of DeepSeek V3 this quarter?' -> model_name=..., weeks=13) effectively show when to pick each mode. There is no explicit when-not guidance or named alternative tool, so it stops 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?

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), yet the description adds real behavioral context beyond them: the free tier returns counts, ranges and redacted samples while PRO returns names and exact prices, PRO costs $500/month, and prices follow modality-specific units. It does not mention pagination interaction with limit or rate limits, 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?

Purpose is front-loaded in the first clause, followed by the tier gating and unit conventions, which are exactly the two things an agent cannot get from structured fields. The commercial detail ($500/month plus URL) is slightly promotional but still functional; nothing else 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 carries the return-shape burden and does so by enumerating the catalog fields and the free-vs-PRO redaction difference. What is missing is how limit/pagination affects the SKU list and any rate-limit expectations, so it is strong 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 the schema already documents vendor, limit, modality, direction and the API key, including the enum for direction. The description adds unit semantics (per 1,000 tokens, per image, per second, per minute, per 1,000 characters), which clarifies the returned values more than the input parameters, so the baseline 3 is appropriate.

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

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

The description names a specific verb+resource ('everything one vendor sells') and enumerates the payload fields (channel, country, pricing page, model and SKU counts, full price list). That scope is clearly narrower than the sibling list_vendors or get_model_detail, so an agent can tell them apart without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit statement of when to choose this over compare_prices, get_model_detail or list_vendors, and no exclusions. Usage is only implied by the scope of the data returned, plus the implied decision point of free tier vs PRO. Adequate but leaves 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?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so the safety profile is fully covered. The description adds the returned field list but says nothing about pagination, result size, or the free-vs-PRO tier behavior implied by the _atom_api_key parameter.

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, zero redundancy, with the core scope front-loaded and the filter capability 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?

With no output schema, the description usefully names the returned fields and the free/PRO tier distinction is documented in the schema. It is nearly complete, lacking only scale/pagination behavior for a fleet-wide listing.

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

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

Schema description coverage is 100%, so the baseline is 3. The description restates the channel/region/country filters but adds no syntax, accepted values, or matching behavior beyond what the schema already documents (including channel codes DEV/CLD/PLT/NCL).

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 (list) and resource (every vendor in the Attic Standard fleet) and enumerates the returned attributes (channel, country, region, pricing page). It does not distinguish itself from the nearby sibling get_vendor_catalog, which sounds like it could overlap, 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?

It says 'Filter by channel, region or country,' which implies the intended use of the filters, but gives no explicit when-to-use guidance, no exclusions, and does not route the agent to an alternative tool for deeper vendor data.

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 read-only, non-destructive, idempotent, and closed-world behavior. The description adds critical context beyond annotations: free tier returns counts/ranges/redacted samples while PRO returns full vendor, model, and exact prices; results are sorted cheapest first; and it explains unit semantics for token vs other modalities. It could mention rate limits or pagination behavior, but the tier distinction is a strong addition.

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 core purpose and uses clear examples. The first sentence is dense but informative, and the subsequent sentences about tiers and units earn their place. Overall efficient, though slightly 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?

With no output schema, the description carries the full burden of explaining return values. It does so by describing what free vs PRO tiers return and noting the sort order and units, which is sufficient for an agent to call the tool correctly. Pagination is covered by the input schema's limit/offset.

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 significantly exceeds that by providing two concrete examples that map natural-language queries directly to parameter values (e.g., open_source="true", modality="Text", direction="Output", max_price=0.0005) and by clarifying that token prices are per 1,000 tokens while other modalities use their own units.

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

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

The description states a specific verb+resource: 'Search every priced SKU' and lists the filter dimensions. This distinguishes it from siblings like compare_prices or get_model_detail, which serve narrower purposes, even though no sibling is named 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?

No explicit when-to-use guidance or alternatives are provided. The examples imply usage scenarios for translating natural-language queries into parameters, but they do not tell the agent when to select this tool over siblings such as compare_prices or get_price_history.

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