Bullion Price Check

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 still earns credit by disclosing the aggregation constraint ('Aggregates only: no dealer is named') and the attribution/licensing of the index row plus its dealer count — context an agent could not get from 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?

A single dense sentence that front-loads the action and then lists the returned metrics in the order an agent would care about them. No filler, though the enumerated metric list makes it longer than strictly needed.

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 present, the description carries the return-value burden and does so thoroughly (premium over spot, p25/median/p75, percentile rank, index row plus dealer count). The remaining gap is behavior when neither your_price nor your_premium_pct is supplied, which neither schema nor description resolves.

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 each parameter carries a substantive description (spot source override, payment list, slug format), so the schema does the heavy lifting. The description adds only the parenthetical 'your asking price (or premium %)' and leaves the interaction between your_price and your_premium_pct, and the valid no-price case, to 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?

States a specific verb (benchmark) and resource (your asking price / premium vs US dealer asks) and enumerates exactly what comes back. The purpose is unambiguous, but it never names the adjacent siblings (premium_over_spot, get_premium_index) so the agent must infer the boundary itself.

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?

Opening phrase 'Benchmark your asking price' implies the use case, and 'for one tracked product' hints at scope, but there is no explicit when-to-use / when-not, no mention of prerequisites (e.g. needing a tracked product from list_products — only stated inside the schema), and no comparison against the many premium-related siblings.

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 bar is lower, yet the description still adds substantial context: the four possible status values (exempt, partial, taxable, no_sales_tax), the accompanying explanation, threshold logic, official source URL, last_reviewed date, provenance (same table as the Bullion Price Check guide), and a legal disclaimer. That is real behavioral disclosure 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?

Front-loaded with the core question and kept to a few dense sentences that each carry information. Minor filler remains — the 'same table as the Bullion Price Check sales tax guide' provenance line and the trailing enumeration endpoint are useful but slightly tacked-on.

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 fully compensates by enumerating the returned fields (status, explanation, threshold logic, source URL, last_reviewed) and the four status values. Combined with input guidance and the disclaimer, an agent has everything needed to call and interpret the result.

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 a 3 is the baseline, but the description adds purpose the schema does not: amount exists 'to apply the state's threshold' and product_type is framed as coin vs bar for eligibility logic. It reinforces rather than repeats the schema's meaning.

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 question-form verb+resource: whether a gold/silver/platinum/palladium purchase is subject to state sales tax in a US state or DC. That is unmistakably distinct from every sibling (spot prices, premiums, melt value, dealer quotes), none of which touch tax treatment.

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

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

States the required input (2-letter state code or name) and the optional inputs that refine the answer, plus a scope caveat ('General information, not tax advice') and an enumeration path ('GET /api/v1/sales-tax lists all 51'). It gives clear context for use but never explicitly names a sibling or an exclusion case, 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), and the description adds real behavioral context beyond them: strict price-only ranking, an explicit statement that 'Partner' dealers cannot buy rank, a 24-hour staleness cutoff, and defined failure behavior that names the closest tracked products rather than silently substituting a different weight.

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 sentences, front-loaded with the resource and sort order, then ranking-integrity, freshness, and error behavior in descending importance. No filler and every clause carries information an agent would otherwise have to guess.

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 carry the return-shape burden and covers ordering, freshness, and the error case well. It stops short of saying what fields each dealer row contains or whether the limit is applied before or after filtering, which is a modest remaining gap for a lookup tool.

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

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

Schema coverage is 100%, so product/limit/payment are already fully documented in the schema, making 3 the baseline. The description reinforces the weight-matching rule for product but says nothing about the payment enum or the limit cap, so it adds little beyond the 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 — current listed dealer prices for one tracked product, returned lowest-first. That resource is clearly distinct from the sibling tools (get_spot_prices, get_premium_index, premium_over_spot), so an agent can route 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?

Usage context is implied rather than stated: 'one tracked product' plus a 24-hour freshness window tells the agent what data it will get, and the not-tracked error behavior is spelled out. However, it never says when to prefer this over get_spot_prices or get_premium_index, nor does it name list_products as the prerequisite for finding a slug (that only appears in the schema).

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered. The description's value-add is disclosing the statistical content of the response (medians, 7-day windows), but it says nothing about data freshness, coverage of 'tracked products', or what happens when the optional filter is omitted.

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?

One front-loaded sentence with no filler; each clause maps to a returned statistic. It is dense but every phrase carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description must carry return-value semantics, and it does list the metrics — but leaves open units (percent vs. currency), the meaning of 'today' (timezone/as-of), and the behavior of the unset `metal` filter. Adequate but with real gaps for a data-retrieval tool.

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

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

The single `metal` parameter has 0% schema description coverage and is never mentioned in the description. The enum values are self-explanatory, but since the parameter is optional (0 required), the description should state what omitting it does — all metals, or a default — and it does not.

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 (Bullion Premium Index) and enumerates exactly what is computed per product: today's lowest premium over spot, dealer median, and 7-day median/minimum. It is clear what the tool returns, but it never distinguishes itself from the close sibling premium_over_spot, leaving the agent to infer the difference from the aggregate/statistical framing alone.

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 statement of when to use this versus premium_over_spot, get_dealer_prices, or true_cost, and no prerequisites or exclusions. The agent must guess based on the word 'Index' that this is the aggregate view rather than a per-quote lookup.

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 that values are 'live' with individual read timestamps, which is useful context beyond annotations, but it says nothing about freshness windows, caching, or failure behavior when a source is unavailable.

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?

A single sentence that front-loads the resource (spots) then the units and extras (USD/troy ounce, read times, ratio). Every clause carries information and none 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 present, the description carries the burden of describing returns, and it does so adequately: three metals, currency, unit of measure, timestamps and the ratio. It falls short only on runtime behavior an agent might care about, such as refresh cadence or what happens if a feed is stale.

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 to document and the baseline is 4. The description correctly spends no words on inputs and instead covers the shape of the result.

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 ('get spot prices') and enumerates exactly what comes back: gold, silver and platinum in USD per troy ounce, with read times and the gold-silver ratio. It does not differentiate from siblings such as gold_silver_ratio or get_dealer_prices, which overlap on content.

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 infer this is the tool for current market spot prices rather than dealer, premium or melt figures. There is no explicit when-to-use or when-not-to-use statement, and the overloading with gold_silver_ratio (which returns a subset of this output) is never addressed.

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), so the description's job is to add context. 'Live' adds freshness information, but it is ambiguous — real-time, delayed, or cached — and, given openWorldHint=false, an agent may wonder whether data is truly live or from a static snapshot. The definition of the ratio units is genuinely useful; nothing is said about rate limits or staleness.

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?

A single front-loaded sentence with a parenthetical definition and no filler. Every clause carries information; there is nothing to trim without losing meaning.

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 must convey what comes back — yet it never says whether the converter returns a converted weight, a currency amount, or both metals' values, nor the precision or units of the returned ratio. For a simple two-parameter, zero-required tool this is adequate but leaves the response shape to guesswork.

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 50%: amount_ozt is documented in the schema, while direction is only an enum. The description's 'ounces of silver one ounce of gold buys at spot' implicitly establishes the gold_to_silver direction, which adds some value, and 'optional ounce converter' hints that amount_ozt is optional. However, it never explains the silver_to_gold inverse or when each direction applies, leaving half the parameter space to inference.

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

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

Names a specific resource (the gold-silver ratio) and defines it precisely as 'ounces of silver one ounce of gold buys at spot', which is far more informative than the title alone and separates it from price-fetching siblings like get_spot_prices or get_dealer_prices. It never explicitly contrasts itself with any of the nine siblings, 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?

The phrase 'with an optional ounce converter' implies the two usage modes (read the ratio, or convert an amount), but there is no explicit when-to-use, when-not, or pointer to the relevant alternatives such as get_spot_prices for raw prices or melt_value for value calculations. Usage is inferable but not 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 safe/idempotent/closed-world profile, so the description's added value is the disclosure of outputs beyond the headline number: the 0.715 oz worn-coin figure and today's lowest dealer ask per $1 face. It doesn't say where prices come from or whether results are cached, but the extra context is meaningful.

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 the primary purpose and alloy breakdown first, then the bonus outputs. No filler or repetition of the title.

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 previews the returned fields (silver content, melt value, worn figure, dealer ask). It's nearly complete for a 2-parameter read-only calculator; a note on which price source/spot basis is used would close the remaining 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% and the enum already maps each code to an alloy, so the description's restatement of 90/40/35 adds little syntax or format detail. It does clarify that face_value is the dollar amount, but the schema already says that.

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 pair ('silver content and melt value') on a specific resource ('US junk silver coins by face value'), and the parenthetical alloy breakdowns make it unmistakably distinct from generic siblings like melt_value or scrap_gold_value.

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 coin-type framing implicitly tells the agent this is the face-value-based calculator for junk silver, but it never explicitly says when to choose it over melt_value or premium_over_spot, nor states any prerequisites or exclusions.

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 the safety bar is low. The description still adds real context: the prices are 'today's lowest listed dealer price' (a freshness and aggregation guarantee) and the listing is complete rather than sampled or paginated. It does not discuss ordering or result size, so a 4 rather than 5.

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

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

Three short sentences, each doing work: what is returned, how to use the result, and the completeness guarantee. Front-loaded with the resource and payoff, zero filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description steps in to name the returned fields and the price semantics, which is exactly what an agent needs. Minor gaps: the optional metal filter and whether results are ordered or truncated are unmentioned. Overall complete enough to call 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% and the single 'metal' parameter has a documented enum, so the schema carries the semantics. The description never mentions the metal filter, so it adds nothing beyond the schema here. Baseline 3 applies.

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

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

Specific verb ('List') plus resource ('bullion products Bullion Price Check tracks') and it enumerates the returned fields (slug, name, metal, troy oz) plus the lowest dealer price. An agent can distinguish this catalogue tool from the pricing siblings (get_spot_prices, get_dealer_prices, get_premium_index) without opening any schema.

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

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

Explicitly routes the agent downstream: 'Use a slug with get_dealer_prices', which names a concrete sibling and the handoff value. It also sets an important boundary ('a product that is not listed is not tracked'), which tells the agent not to go hunting for untracked products. No explicit when-not-to-use beyond that, so not 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 establish that this is a read-only, idempotent, non-destructive operation. The description adds useful context about the live-spot calculation and supported units, but it does not disclose the source or freshness of the live spot price, currency assumptions, or any rate limits, so it adds only moderate behavioral value beyond 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?

The description is a single, front-loaded sentence that states the purpose and formula immediately, followed by unit support. There is no wasted text, and an agent can extract the core behavior at a glance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich annotations and mostly documented schema, the description is close to complete for parameter semantics, but it omits the return value shape, currency, and live-spot data source. Because there is no output schema, the missing return details are a real gap for a financial calculator.

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 75%, and the description supplements the schema by naming the supported metals, tying weight to troy ounces, grams, kilograms, or pennyweight, and clarifying the weight x purity x spot calculation. This meaningfully reinforces the parameters, though it does not explain the purity fraction explicitly 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 clear resource and operation: melt value for gold, silver, or platinum items at live spot using weight x purity x spot. It is specific enough to identify the core function, but it does not explicitly distinguish itself from overlapping siblings such as scrap_gold_value or junk_silver_melt.

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 explains what the tool calculates but gives no guidance on when to use it instead of alternatives. Sibling tools like scrap_gold_value and junk_silver_melt overlap in domain, so the absence of routing guidance is a meaningful gap.

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

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

Annotations already declare this a read-only, idempotent, non-destructive lookup, so the safety profile is covered. The description adds genuine behavioral context unavailable from annotations: the response is mode-dependent, and the product-slug path returns extra comparative context (today's lowest, median and highest listed dealer prices). It stops short of specifying the premium's form (percentage vs absolute currency), which is a real gap given there is no output schema, keeping it from 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 sentences, front-loaded with the core purpose, then the two input modes in the order an agent would evaluate them. No filler or restatement of the tool title.

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 five-parameter read-only calculation tool with full schema documentation and no output schema, the description covers purpose, both input paths, cross-references list_products, and sketches the richer output available on the product path. The one meaningful omission is the format of the returned premium, which an agent would otherwise have to discover by 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 description coverage is 100%, so the schema already documents every parameter, including the metal/weight_ozt pairing, the product name-matching rule, and the payment enum. The description reinforces the metal + weight combination and points to list_products for slugs, which is a helpful nudge, but it doesn't add semantics beyond what the schema states. Baseline 3 applies.

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

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

The description states a concrete computation (premium over spot) tied to a specific input (a price you were quoted), which is enough for an agent to know this is a pricing-analysis tool rather than a raw price lookup. It does not, however, explicitly differentiate itself from close siblings like get_premium_index, get_dealer_prices, or get_spot_prices, so an agent must infer the boundary from the input-mode hints.

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 clearly distinguishes two usage modes: pass a tracked product slug for a comparative view against dealer listings, or pass metal + weight for an arbitrary item. That is actionable routing guidance for input selection, but it offers no when-not-to-use guidance and no explicit pointer to alternative tools for the cases this one doesn't cover.

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 safety is covered. The description adds genuinely non-obvious behavior: unknown fields, IRA eligibility and 1099-B reportability return null and are enumerated in a 'missing' list, and no values are estimated. It does not say what happens on an unrecognized product string (error vs. null), which is the one remaining behavioral gap.

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

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

Front-loaded with the core statement, then scope, then edge-case behavior — a sensible order with no filler sentences. It is dense and slightly run-on (the recompute formula is embedded mid-sentence), but every clause carries information an agent needs.

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 one parameter, no output schema and full annotation coverage, the description supplies the return-field list, the null/missing convention, coverage boundaries, and input-discovery routing. Nearly complete; only failure behavior for an invalid product identifier 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 coverage is 100% and the single parameter is well documented, so the baseline is 3. The description still adds value by naming concrete spec-only inputs ('$20 double eagle', 'pamp 20g', morgan-dollar) and pointing at list_products, which the schema only gestures at.

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+resource ('Official specs for a coin or bar') and enumerates exactly what is returned: mint, country, fineness, gross/fine weight, pure metal, denomination, series, per-row source, plus a recompute check. It also scopes coverage (tracked products plus spec-only coins such as pre-1933 gold and PAMP bars), which clearly separates it from siblings like melt_value or premium_over_spot that compute derived numbers rather than report specs.

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 parameter description routes the agent to list_products for slug discovery and clarifies that either a tracked slug or a spec-only name is acceptable, giving clear context for invocation. It does not state when *not* to use this tool or name a competing tool for spec-adjacent needs, so it stops short of full alternative routing.

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, closed-world), so the description's job is to add behavior — and it does: stateless, never invents bids, totals rounded once from the unrounded unit, quotes expire after valid_seconds, and the spot used is labeled with source and timestamp. It does not spell out failure modes (e.g. missing spot, unlisted product), which keeps this at 4 rather than 5.

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

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

Front-loads the verb and the two classes, then packs defaults and formulas into single clauses without restating the schema. The parenthetical tier lists are dense but earn their space because those numbers are unavailable elsewhere; a slightly tighter structure with the return-value sentence moved up would be ideal.

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 16-parameter tool with no output schema, the description carries the return contract itself: unit and total, rounding rule, expiry, spot_source/spot_asof, sell-side percentiles, and the conditional anonymous bid benchmark with its privacy constraint. Defaults and precedence for side, class, and tier are all stated, so an agent can call it correctly without further inference.

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 exceeds it by supplying semantics the schema does not contain — the actual tier percentages (96/97.5/98.5 bullion, 90/93/95 scrap), the sell-side formula melt x (1 + margin_pct/100) + margin_usd, and the rule that purity is applied once when combined with karat. That composite behavior is exactly what an agent cannot infer from the individual properties.

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 ("Price a dealer ticket from spot") and immediately splits the domain into two named classes, bullion and scrap. That split, plus the buy/sell framing, is what separates it from siblings like melt_value or scrap_gold_value, which compute single-value metrics rather than a priced dealer ticket with expiry and margin rules.

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 concrete selection logic: which class applies, what each side means, what defaults fire (target tier for buy quotes, buy for scrap, sell otherwise), and that tier/offer_pct and margin rules are alternatives rather than combined. It stops short of naming a sibling tool and saying when to use that instead of quoting here, so it is clear context without explicit exclusions.

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 readOnly, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description still adds real context: the valuation is tied to live spot prices, uses a karat/24 formula with 24k treated as 99.9% pure, and the optional offer yields a share-of-melt comparison.

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 core operation, and the optional offer behavior is deferred to the end. The parenthetical purity detail earns its place because it defines the calculation.

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 the work of naming the returns (melt value, and share-of-melt when an offer is supplied). It leaves the currency/units of the output implied rather than stated and does not specify the spot-price source or refresh behavior.

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

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

Schema coverage is 75% and the one undocumented parameter (weight) is self-evident. The description adds semantics the schema lacks: the purity math behind karat, the spot-price source of the valuation, and that offer_usd is interpreted as a percentage of melt rather than a raw difference.

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 computation (full melt value) on a specific resource (scrap gold/jewelry) parameterized by karat and weight against live spot. An agent can tell what it returns, though it never contrasts itself with the sibling 'melt_value', which sounds like it could compute the same thing.

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 implied by the input framing (give karat and weight to get melt; optionally give an offer to see the percentage). There is no explicit when-to-use or when-not-to-use guidance, and no routing to the overlapping sibling 'melt_value' or 'junk_silver_melt'.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so the safety profile is covered. The description adds that mode 2 relies on each dealer's published shipping and payment fees, which hints at data provenance, but says nothing about error behavior for an unknown product or what the ranked output actually contains.

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 core purpose, then the two modes in a parallel structure. Every clause carries information an agent needs to select a mode; 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?

With no output schema, the description correctly compensates by stating the return values: an all-in total in mode 1 and a dealer ranking by delivered total in mode 2. Given 7 all-optional parameters, it is adequate, though it omits failure cases such as an unrecognized product slug.

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 86%, and the schema itself already labels price as 'Mode 1' and product as 'Mode 2 when price is not given'. The description restates that mode mapping with little added detail such as fee stacking order or rounding, so the baseline of 3 applies.

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

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

States a specific computation ('delivered cost of a bullion order') and enumerates two concrete operating modes with their inputs, so an agent immediately knows this is an all-in landed-cost calculator. It does not name sibling tools such as premium_over_spot or melt_value, which overlap slightly, so the differentiation is inferential rather than explicit.

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 a clean selection rule: use mode 1 when a price is supplied, mode 2 when a tracked product is supplied instead of a price. It does not name alternatives or say when not to use this tool (for example, when only spot prices are needed), leaving that 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 establish read-only, idempotent, non-destructive behavior, and the description adds real context beyond them: a hard cap of 50 lots, the fallback spot source (Bullion Price Check / gold-api.com), and that caller-supplied spot is labeled spot_source=caller in the answer. It does not discuss pricing staleness or failure behavior when a product name has no match.

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 tight sentences: the first front-loads what is valued and what is returned, the second carries the operational envelope (50-lot cap) and transport format. No filler despite a dense set of facts.

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 the work of naming the resulting figures (melt, dealer ask, gain vs melt, spot_source label), which is what an agent needs to decide the tool answers its question. Missing only edge-case behavior, such as what happens with untracked or ambiguous product names.

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 documenting a REST serialization form (sku:qty[:cost_basis] comma-joined) that appears nowhere in the schema, and by clarifying that cost basis is what triggers the unrealized-gain computation. Spot parameters themselves are left entirely to 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?

Names a specific verb and resource (value a list of inventory lots of tracked products) and enumerates the outputs produced: melt value, median US dealer ask, cost basis and unrealized gain. It does not explicitly distinguish itself from near-siblings such as melt_value or true_cost, so it falls just 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?

Usage is only implied: 'a list of inventory lots' and 'up to 50 lots' signal a batch valuation call, and cost basis being optional implies you pass it only when you want gain figures. No explicit when-to-use / when-not-to-use or named alternative (e.g. melt_value for a single item) is given.

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