Attic Standard

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

Annotations already cover the read-only/idempotent safety profile, and the description adds the non-obvious behavior that matters: the free tier redacts vendor/model names and exact prices while PRO returns them, and that units vary by modality (per 1k tokens, per image, per second, per 1k characters). That tier-gating and unit disclosure is exactly the kind of context schema and annotations cannot express.

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 capability, then tier behavior, then units, then examples — a logical order with little waste. It is dense but the pricing/paywall URL sentence sits close to promotional, costing it a point against strict conciseness.

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: it lists the aggregate fields produced (counts, ranges, spread ratio) and the per-offer detail including channel, plus how output differs by tier. An agent has enough to call it and interpret the response without reading source.

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 earns above that by explaining the unit semantics behind `direction` (per 1,000 tokens vs per image/second/minute/character) and by demonstrating the model_name vs model_family split through examples. It doesn't clarify `limit` or the 200 maximum, but the schema already does.

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 precise verb+resource+scope: 'The same model, or a whole family, priced across every vendor that sells it', and then enumerates the exact outputs (cheapest/highest offer, vendor count, spread ratio, per-offer channel). This clearly separates it from siblings like get_model_detail, get_vendor_catalog or get_price_history, which deal with single models, catalogs or time series rather than cross-vendor comparison.

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 explicitly show the two modes of use (model_name for a single model, model_family + direction for a family aggregation), which resolves the main ambiguity an agent would face. It stops short of naming when NOT to use this tool or which sibling to pick for historical or per-vendor data, so no exclusions are 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 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, and the description adds substantial context beyond them: free tier returns redacted samples while PRO returns vendor/model names and exact prices, plus the per-unit pricing convention. Missing only things like pagination or result-size behavior.

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

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

Front-loads coverage before distributions and ends with a useful unit convention, but the long parenthetical enumerations (vendors and pricing services, in total, by channel...) are dense and slow to parse.

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 characterize returns, and it does: counts/ranges/redacted samples for free, names and exact prices for PRO, plus unit semantics. Adequate for correct invocation, though filter behavior and result shape could be tighter.

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%, with both modality and _atom_api_key documented in-schema, so the description needn't restate them. The unit conventions (per 1,000 tokens, per image, etc.) are return-value semantics rather than parameter guidance, so no boost above baseline.

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: market coverage (vendors, pricing services, countries, models, SKUs, indexes) and price distributions by modality/unit/direction. Clearly distinct from siblings like compare_prices or get_price_history, though the verb is generic.

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?

Explains the free vs PRO tier split, which is a key usage consideration, but never states when to choose this over siblings such as get_index_benchmarks or compare_prices. Usage must be inferred from the return content.

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 readOnly, idempotent, closed-world, so safety is covered; the description adds that the response includes vendor and pricing-service totals, which is useful since there is no output schema. It omits relevant behavioral context: the PRO-key gating for vendor-level data and whether results are truncated or paginated.

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, no filler, with the resource definition front-loaded and filtering last. The first sentence is dense with nested parentheticals that slightly slow parsing, 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 read-only, fully documented four-parameter listing tool with no output schema, the description is mostly sufficient: it explains the return content and filtering. It falls short on the PRO-key/free-tier distinction and on steering the agent away from the similar get_vendor_catalog or search_models tools.

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%, with region and channel examples and the DEV/CLD/PLT/NCL codes documented in the schema itself. The description restates the three filter dimensions but adds no example values or matching semantics (exact vs partial matching, multi-value support) 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 states a concrete resource (every pricing service in the Attic Standard fleet) and enumerates the attributes returned (vendor, channel, country, region, currency, pricing page), so an agent knows exactly what listing it gets. It does not differentiate from the closest sibling, get_vendor_catalog, leaving ambiguity about which listing tool to pick.

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?

"Filter by channel, region or country" implies the calling pattern, and the optional-parameter framing aligns with the zero-required-parameter schema. However, there is no statement of when to prefer this over get_vendor_catalog or compare_prices, and no mention of the free-tier vs PRO-key condition that governs vendor/SKU-level 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.