AssayChain — Mineral Intelligence (USGS and Field Runs)

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

With no annotations provided, the description carries the transparency burden. It discloses the cost per query ($0.25) and indicates the data is 'active' US operations, implying current status rather than historical. However, it does not describe any limitations, data sources, or authentication requirements, which are typical behavioral expectations.

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 two concise sentences that front-load the purpose and list output fields, then append the cost. Every word earns its place—no fluff or repetition.

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 single-parameter read-only tool with no output schema, the description covers the core need: what it returns and the cost. It could mention data source or update frequency, but given the simplicity, the description is largely complete and actionable.

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 input schema already provides 100% coverage by describing the commodity parameter as a slug with examples. The description adds the term 'critical mineral' but does not clarify the slug format beyond what the schema already states, so it adds minimal value 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 clearly identifies the tool as returning active US mining operations for a given critical mineral, listing the specific output fields (operator, location, mine type, capacity). The resource and scope are specific, which distinguishes it from sibling tools like supply_share or stockpile_level, though it does not explicitly name alternatives.

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 mentions that the tool works for a given critical mineral, but it does not provide any guidance on when to prefer this tool over sibling tools (e.g., supply_share, blm_claims_data) or any exclusions. No alternatives are mentioned, leaving usage context implicit at best.

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, and non-destructive behavior. The description adds that this is a preview-only tool returning field names and metadata, and that full data requires payment via the x402 protocol. This extra context about the paid endpoint and on-chain provenance is valuable 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 moderately long but structured with distinct clauses: preview nature, mineral list, return values, use cases, and payment model. It is front-loaded with 'Discovery preview' and each sentence provides meaningful information, though the compliance use-case list could be trimmed without losing core purpose.

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 discovery/preview tool, the description adequately covers what it returns, the scope of commodities, and how to access full data. The output schema exists, and annotations cover safety, so the description does not need to detail return formats. It is complete enough for an agent to decide when to invoke this 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?

There is one parameter with a complete enum, and the schema property description already lists valid values (though truncated). The description adds the full list of 20 critical minerals and calls them 'critical minerals', but this is largely redundant with the schema enum. With 100% schema coverage, the description does not need to add much, but it does not explain how the commodity affects the response beyond the enum.

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 clearly states it is a 'Discovery preview' that 'returns available field names, on-chain provenance UIDs, and the paid REST endpoint.' This is specific with a clear verb and resource, and it distinguishes itself from sibling tools like 'benchmark.sample' or 'benchmark.runs' by emphasizing the discovery/preview nature.

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

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

It provides concrete use cases (supply-chain due diligence, UFLPA, EU Battery Regulation, CBAM/CSDDD) and implies when to use it: when you need a preview before paying for full data. It does not explicitly name alternative tools or provide exclusions, but the distinction between preview and paid endpoint is clear.

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 destructiveHint, so the safety profile is covered. The description adds valuable behavioral context: it is a preview returning summary info, full data requires payment, and it covers multiple rig modalities including future rigs under the same schema. No contradictions with 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 two sentences and front-loads the main purpose. The second sentence is dense but packed with relevant details (scope, return fields, paid endpoint). It does not waste words, though the density could be slightly improved by splitting.

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 tool's low complexity (1 optional param, output schema present), the description is quite complete. It covers purpose, return values, scope, and the path to full data. It does not describe output schema details, but that is covered by the output schema itself. Could mention that the preview is free, but that is implied by the paid full data endpoint.

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%, with the only parameter (`attested_only`) clearly described in the schema. The description does not add much parameter-specific meaning, though it mentions 'attested' logs and EAS attestation UIDs in the full data context, indirectly relating to the parameter. Baseline 3 is appropriate given full schema coverage.

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 clearly states the tool's function as a 'Discovery preview' for 'attested mineral-processing field run logs', specifying what it returns (run count, run IDs, date range, paid REST endpoint). It distinguishes itself from the full data endpoint and sibling tools by emphasizing its preview nature and coverage of multiple rig modalities.

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 clearly indicates when this tool should be used: for a quick overview/preview, while full run data requires a paid REST endpoint ($0.10 USDC via x402). It does not explicitly name sibling tools as alternatives, but the contrast with the paid endpoint provides clear usage context.

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 and idempotentHint, but the description adds vital behavioral details: numeric values are replaced with '<number: paid>', provenance fields are included, and the paid REST endpoint URL is returned. This gives the agent a precise expectation of the output without contradicting 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, each earning its place: the first states the free sample purpose, the second explains the value replacement and the output structure, the third ties it to paid usage and lists included fields. No wasted words.

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 simple tool with one parameter, annotations, and an output schema, the description is complete. It covers the tool's purpose, what to expect in the response, how it relates to the paid endpoint, and cost implications. No missing critical context.

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 parameter `commodity` is fully documented in the schema with an enum and description (100% coverage). The description adds no additional semantic detail beyond referring to 'any supported commodity,' so 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 clearly states the tool's function: providing a free sample of benchmark data shape. It distinguishes itself from the paid sibling benchmark.commodity by detailing the key difference (numeric values replaced with '<number: paid>') and naming the endpoint.

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 tells when to use this tool: 'Use this to understand exactly what fields you will receive from the paid benchmark.commodity endpoint before spending $0.10 USDC.' This direct guidance also names the alternative and the cost, making the usage context unambiguous.

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

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

With no annotations provided, the description carries the burden. It discloses the $0.25 per query cost and specifies that it returns active counts, but it does not mention error handling, rate limits, or limitations beyond 'US mining counties'. This is moderate disclosure but leaves some behavioral aspects uncovered.

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 three short sentences, each adding distinct value: data source and scope, return type, and cost. It is front-loaded and free of unnecessary words, making it highly concise and well-structured.

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 no output schema, the description adequately explains the return type (active lode/placer/millsite counts) and includes cost information. It could mention output format or error conditions, but for a simple two-parameter query tool, it covers the essential context.

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 input schema provides complete descriptions for both parameters, including examples. The tool description adds no additional parameter semantics, but since schema coverage is 100%, the baseline of 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 clearly states the tool's function: it returns BLM LR2000 mining claims data by state and county, specifically active lode/placer/millsite counts. This includes a specific verb ('returns'), the resource ('BLM LR2000 mining claims'), and a clear scope, distinguishing it from sibling tools.

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

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

The description implies usage for retrieving BLM mining claims data, but it does not explicitly state when to use it versus alternatives or provide exclusion criteria. The cost and data type offer context, but there is no direct 'when to use' guidance.

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

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

Annotations already indicate read-only and idempotent behavior. The description adds valuable context: return fields (restricted status, effective date, source) and the payment/API details (0.25 USDC, GET endpoint, x402 on Base). No contradiction with 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?

Two concise sentences: the first states purpose and scope, the second provides critical payment and endpoint details. No redundant filler or unnecessary background.

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 simple one-parameter tool with output schema and annotations, this description covers the essential information: what it does, key return fields, and required payment. Slight ambiguity remains about what 'full data' means without payment and how non-restricted commodities are handled.

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 schema already provides full parameter coverage with an enum and description. The description lists some relevant minerals but does not add deeper semantics about how the commodity string should be formatted or what values are valid 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?

Description clearly states the tool checks China export restrictions for specified minerals and lists examples. This specific verb plus resource scope distinguishes it from sibling tools like supply_resilience or criticality.crosscheck.

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

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

Use case is implied (check export restriction status for a commodity), but there is no explicit guidance on when to prefer this over alternatives or when not to use it. The payment caveat is practical but not a substitute for usage direction.

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 destructiveHint, so the safety profile is covered. The description adds useful context about return content (provenance UIDs, IPFS-pinned source, snippet) and characterizes the search as 'BM25-lite', hinting at approximate ranking. It doesn't contradict 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?

Two dense sentences: first states what the tool does and returns, second gives usage guidance. Every clause earns its place with specific details and alternatives. No fluff.

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 tool has rich output schema, annotations, and full schema parameter coverage, the description still adds critical context: the corpus size, what provenance UIDs guarantee, and how to proceed after search. It is complete for an agent to select and invoke 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%, with all three parameters (query, kind, top_k) well-documented in the schema. The description does not add parameter-level detail beyond what the schema provides, but it reinforces the intended use of the query parameter with contextual follow-up actions. 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 clearly states a specific verb ('Free lexical search') and resource ('all 199 EAS-attested files'), with a defined scope (20 USGS benchmarks + 179 district records). It also distinguishes from siblings by naming alternatives (benchmark.commodity, district.history) and the paid REST endpoint.

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?

Explicit guidance is given: 'Use this to discover which attested records cover a topic', followed by two concrete follow-up options (paid full data or paid synth answer). This tells the agent when to use this tool versus alternatives.

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 and idempotent behavior, but the description adds key context: full data requires a $0.25 USDC payment via x402 on Base, and mentions the API endpoint. This goes beyond annotations by disclosing a paywall constraint and delivery mechanism, which is valuable behavioral information.

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 two sentences, directly front-loaded with the tool's core function, then followed by specific details on outputs and payment. Every sentence adds informational value with no redundancy or 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?

The description explains what the tool returns (crosscheck status for four lists plus jurisdiction count) and flags the payment requirement for full data. The output schema exists, but the description still provides a concise preview of the response structure, making it fairly complete for a relatively simple one-parameter 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% with a single 'commodity' parameter that has a clear enum and description. The description adds context about the 20 commodities and the crosscheck nature, but does not elaborate on parameter syntax or usage details beyond what the schema already provides, so a baseline of 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 clearly states the tool's function: multi-jurisdiction critical mineral classification across specific lists (US DoD, EU CRMA, IEA, Japan METI). It uses a specific verb ('returns crosscheck status') and resource ('20 commodities'), distinguishing it from sibling tools like china_trade_control or supply_resilience.

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 usage for cross-checking critical mineral classifications across multiple jurisdictions and commodities, but does not explicitly state when to prefer this tool over alternatives. No exclusions or comparisons to sibling tools are provided, leaving usage context somewhat implied rather than explicit.

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 and idempotent behavior. The description adds value by revealing the paywall for full data, the MRDS source, and the specific fields returned in the free preview. No contradiction with 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 concise and front-loaded with the core purpose, followed by use cases and payment conditions. It is slightly long but every sentence serves a clear function.

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?

The description covers purpose, return contents, use cases, and the premium full-record option. An output schema exists, so return-value details need not be spelled out. Overall, it is complete for a simple read-only preview 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 input schema fully describes all four parameters with examples, and the description does not add further parameter-level detail. With 100% schema coverage, the baseline of 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 clearly states that this tool provides a free preview of mining district records for the US or Mexico, with specific contents (field inventory, commodity summary, discovery year, deposit count). This directly differentiates it from the paid full-record endpoint and any sibling tools.

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

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

The description identifies clear use cases (DoD/DFC project assessments, UFLPA research, production context, developer research) and contrasts the free preview with the paid full record. It does not explicitly name alternative tools, but the context is strong enough to guide selection.

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

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

With no annotations, the description carries the burden of disclosing behavior. It adds a cost of $0.25 per query and specifies the output scope (completed/planned surveys), which is useful. However, it lacks details on response format, error handling, or any side effects, leaving gaps for a read operation.

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 two sentences, efficiently conveying purpose, scope, and cost without redundant wording. Every sentence contributes valuable information, making it highly concise and well-structured.

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 single-parameter tool with no output schema, the description provides essential context: data source, state filtering, survey types, and cost. It does not detail return structure, but the simplicity of the operation reduces the need for more. Overall, it is adequately complete.

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

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

Schema description coverage is 100% for the single 'state' parameter, which already documents its meaning and format. The description adds no extra parameter semantics beyond stating 'by state,' so it does not exceed the schema 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?

The description clearly states the tool returns USGS Earth MRI focus area data by state, specifically completed and planned geophysical/geochemical surveys. This identifies the resource and the action (returns), though it does not explicitly differentiate from sibling tools like geophysics_surveys.

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 tool is used with a state input but provides no guidance on when to choose this tool over alternatives. There is no mention of exclusions, prerequisites, or comparisons to sibling tools, leaving the agent without decision-making context.

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 the tool as read-only and idempotent. The description adds valuable behavioral context beyond this, including the payment requirement ('$0.50 USDC via GET /api/esg/{commodity} using x402 on Base') and data sources (ICMM, IEA, Ecoinvent). It does not fully clarify the distinction between preview and full data, as the title 'ESG profile preview' implies a free tier, but the description only mentions payment for 'full data'. This ambiguity prevents a perfect score.

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

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

The description is composed of three focused sentences, each adding new information: the core functionality and outputs, the target audience, and the payment/access details. There is no redundancy or filler, and key information is front-loaded.

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 simplicity (one parameter), the presence of annotations (read-only, idempotent) and an output schema, the description is largely complete. It covers purpose, outputs, audience, and cost. However, it leaves ambiguity regarding whether a free preview exists without payment and what the output structure is, though the output schema handles the latter. The payment/preview clarification would make it fully complete.

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

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

The input schema fully documents the only parameter 'commodity' with an enum of 20 values and a description ('Mineral commodity slug'). The description adds minimal extra parameter semantics, just noting 'all 20 commodities' without detailing slug formats or validation rules. Since schema coverage is 100%, the baseline score of 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 clearly states the tool's function with a specific verb ('Returns') and defines the resource scope ('ESG intelligence for critical minerals'), enumerating concrete outputs (recycling metrics, carbon intensity, regulatory exposure). This distinct functionality differentiates it from sibling tools like supply_resilience or criticality.crosscheck, which focus on other aspects.

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 identifies the primary use case: 'Sustainability analysts, compliance officers, and carbon-accounting agents use this for ESG due diligence.' This provides clear context for when to use the tool. However, it does not explicitly state alternatives or when not to use it, which would elevate the score to 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?

The annotations already mark the tool as read-only and non-destructive. The description adds valuable behavioral details: the estimate is free, expires in 15 minutes, returns a quality grade, and includes an auto-refund for grade D. It also explains the payment via x402 USDC on Base. These go well beyond the annotation hints.

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 two dense sentences that front-load the core purpose, then list return fields, the next step, and the refund policy. Every clause adds value, and there is no filler. It is appropriately structured for an AI agent to extract key info quickly.

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?

The description covers the tool's purpose, return payload (including nested cost_breakdown), expiry, refund policy, and integration with extract.run. With an output schema present, it does not need to detail every return field. This is a complete, self-contained description for the tool's complexity.

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 schema covers 100% of the parameters with descriptions (source_url with max size, source_type as an optional hint). The tool description repeats the source type list but does not add new semantics; it mainly provides workflow context. Given the high schema coverage, a baseline of 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 clearly states the tool provides a free probe and price quote for extraction, enumerates supported document types, and explicitly distinguishes itself from extract.run by noting the estimate_id is used with that sibling. This makes the purpose unmistakable and differentiates it from related tools.

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

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

The description provides a clear workflow: get an estimate, then use extract.run with the estimate_id. It also mentions the free nature and refund policy, giving context on when to use. However, it does not explicitly list any 'when not to use' scenarios or mention alternative tools like extract.result, so it's clear but not exhaustive.

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 and destructiveHint=false. The description adds meaningful behavioral details: the need for an HMAC token (authentication) and the 24-hour expiration (TTL), which are not captured in the annotations. It also outlines the returned fields, contextualizing the read operation.

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 two sentences: the first clearly states the purpose, and the second efficiently lists the returned fields and operational constraints. No filler or redundancy.

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 simple 2-parameter fetch tool, the description covers purpose, prerequisites (token, previous payment), return structure, and TTL. Combined with the annotations and existing output schema, it is fully sufficient for an agent to invoke the tool 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?

Both parameters (job_id and token) have descriptions in the schema, giving 100% coverage. The description references the token requirement but does not provide additional parameter semantics beyond what the schema already explains. 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 starts with 'Fetch the structured extraction result for a previously paid job', which specifies the verb (fetch), resource (extraction result), and constraint (previously paid). This clearly distinguishes it from sibling tools like extract.run and extract.estimate.

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

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

It provides clear context on when to use the tool: after a paid run, requiring an HMAC token from result_url, and notes a 24-hour TTL. However, it does not explicitly name alternatives or state when not to use it, so it lacks 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?

The description adds substantial behavioral context beyond the readOnlyHint and idempotentHint annotations: it explains that MCP cannot carry the X-PAYMENT header, why the tool returns guidance rather than executing the POST, and details the result delivery and refund policy. This is rich, honest disclosure with no contradiction to 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?

The description is concise but information-dense, covering purpose, payment, result format, refund, and next steps in a few sentences. It is front-loaded with the core action and each sentence earns its place, with no fluff.

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 tool's moderate complexity and the rich annotations/context, the description is fully complete: it explains the payment ladder, result delivery fields, grade D refund, and the required next action. It also mentions the output schema components (job_id, result, grade, result_url), so nothing essential 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 for the single parameter estimate_id is 100%, with the schema already describing it as 'The estimate_id returned by extract.estimate.' The tool description references estimate_id indirectly via 'after extract.estimate' but does not add new parameter semantics beyond what the schema provides, so the 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 clearly states the tool 'Returns invocation guidance for executing a paid extraction job after extract.estimate,' using a specific verb and resource. It distinguishes itself from sibling tools like extract.estimate and extract.result by focusing on guidance for the paid run rather than estimation or result retrieval.

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 specifies the tool is used 'after extract.estimate' and instructs the agent to 'execute the paid POST directly with an x402 client' after receiving the endpoint and price. This provides clear contextual usage, though it does not explicitly contrast with alternatives like extract.result, so it falls 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?

No annotations are provided, so the description carries the burden of disclosing behavioral traits. It says 'Returns' which implies a read-only operation, and it discloses the cost. However, it does not mention error handling, rate limits, or explicit safety characteristics, so transparency is adequate but limited.

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 three short sentences: it states the subject, the contents, and the cost. Every word earns its place, with no fluff or redundancy. The purpose is front-loaded, making it easy to scan.

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 low-complexity tool with one parameter and no output schema, the description covers the essential context: what it returns, the geographic scope, and the cost. It does not describe the output format or edge cases, but these are less critical given the simplicity.

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 input schema fully documents the sole 'district' parameter with examples and a clear description (100% coverage). The tool description adds no additional parameter semantics beyond what the schema already provides, so the baseline of 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 clearly states the tool's function: it returns historical geophysical survey metadata for US mining districts, specifying the types (aeromag, gravity, EM, radiometric). This specific verb+resource+scope distinguishes it from sibling tools like active_operations or supply_resilience, which are not focused on geophysical data.

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 provides clear context on what data it covers (US mining districts, specific survey types) and mentions the cost per query, which helps decide when to use it. However, it does not explicitly state when not to use it or mention alternative tools, so it lacks exclusions and alternative guidance.

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

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

Annotations already mark readOnlyHint=true and destructiveHint=false; the description adds useful behavioral details by stating 'Free to call' and 'Returns a natural-language answer from a small LLM grounded on the API docs.' This discloses the LLM-based nature, grounding, and cost profile without contradicting 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 well-structured and front-loaded with the main purpose. It uses four concise sentences, but the second sentence's long list of compliance regulations adds length; still, every sentence contributes useful information without redundancy.

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 tool's simple single-parameter schema, output schema, and read-only annotations, the description is complete. It covers what the tool does, what kinds of questions to ask, cost, and the nature of the returned answer, leaving no critical gaps for an agent to select and invoke 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?

With one parameter at 100% schema coverage, the description amplifies the meaning of 'question' by enumerating acceptable topics (e.g., pricing tiers, x402 payment flow, UFLPA compliance). These examples go beyond the generic schema description and help the agent compose richer, more relevant queries.

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

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

The description opens with 'Ask anything about this API' and lists specific topics like commodities, provenance, pricing, and integration, making the tool's verb and resource clear. It distinguishes itself from sibling data-lookup tools by positioning this as a natural-language sales/API Q&A agent that returns LLM-grounded answers.

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 provides clear use-context: when to ask about API capabilities, compliance use cases, and documentation-related questions. It does not explicitly name alternative tools or state when not to use it, but the examples sufficiently imply when this tool is appropriate versus specialized sibling tools.

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

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

Annotations already declare read-only, idempotent, and non-destructive behavior. The description adds beyond that: the $0.25 USDC payment requirement, the GET endpoint using x402 on Base, and the returned data fields. This enriches the agent's understanding of cost and API usage.

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, each with a distinct purpose: what the tool does, what it returns, and who uses it with cost details. No redundancy or fluff.

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 single-parameter read-only check, the description covers purpose, outputs, payment, endpoint, and use case. With an output schema present and annotations clarifying safety, it leaves no critical gaps.

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 schema fully covers the commodity parameter with an enum and description. The description only mentions '20 minerals' without adding additional parameter-level semantics beyond the schema, so the baseline of 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 clearly identifies the tool as a DLA strategic stockpile check for 20 minerals and enumerates specific outputs (held status, quantity tonnes, DLA status). This distinguishes it from sibling supply-chain tools by its government stockpile focus and concrete return fields.

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

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

It names the intended audience (defense-contractor supply-chain agents) and use case (gauge DoD mineral security), providing clear context for when to use. However, it does not explicitly exclude alternative tools or name when not to use it.

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 and non-destructive, but the description adds important behavioral context: the $0.50 USDC payment requirement and the use of x402 on Base. It also describes the return structure. No contradictions with annotations. It doesn't cover error handling or rate limits, but the added payment and endpoint details merit a 4.

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 three sentences long, each earning its place: purpose and outputs, target users, and payment/endpoint. It is front-loaded with the core functionality. Slightly long for a simple tool, but the complexity of the outputs justifies the length.

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 an output schema present, the description sufficiently covers the tool's purpose, outputs, use case, and payment requirement. It lacks potential edge-case details (e.g., partial data behavior) but overall provides a complete picture for an agent to invoke 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?

The schema provides 100% coverage with a full enum for 'commodity' and a clear description ('Mineral commodity slug.'). The tool description adds only general context (e.g., '20 critical minerals') but no additional parameter semantics. Baseline 3 is appropriate because the schema already carries the weight.

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

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

The description states a specific verb and resource: 'Supply chain resilience score + scenario analysis for 20 critical minerals.' It enumerates concrete outputs (0-100 score, vulnerability level, 5-factor breakdown, 3 scenario tests) that clearly distinguish it from siblings like supply_share and stockpile_level. The intended audience (procurement agents, supply-chain strategists) further clarifies its purpose.

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 provides clear context: 'Procurement agents and supply-chain strategists use this for vulnerability triage.' This implies the tool is for resilience assessment rather than raw data lookup. However, it does not explicitly mention alternatives or exclusions, 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 declare readOnlyHint=true and idempotentHint=true, which establishes safety. The description adds valuable behavioral context: the exact fields returned, the 'Top-3' limitation, and the paywall for full data via a specific endpoint. No contradiction with 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?

Two sentences: the first front-loads purpose and outputs; the second explains access/payment. No redundant wording, no unnecessary detail. Every sentence 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 an output schema present, the description need not repeat return structures. It covers the payment requirement, endpoint, and protocol (x402 on Base), which are essential for invocation. Minor gap: doesn't state data freshness, which is not critical. Complete enough for a single-parameter read 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 parameter (commodity) is fully documented in the schema with an enum and description. The description merely echoes '20 commodities' without adding detail about specific values or selection behavior. With 100% schema coverage, the baseline of 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 clearly states the tool's function: 'Top-3 producer supply concentration for 20 commodities.' It identifies the resource (commodities) and the specific output (country, market share %, HHI, etc.). However, it does not differentiate from sibling tools like supply_resilience or china_trade_control, 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 description implies usage through its purpose but provides no explicit 'when to use' or alternatives. The payment requirement ($0.25 USDC via x402) is an access constraint, not usage guidance. Since siblings exist but are not referenced, the usage context is only weakly implied.

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