MiningBridge Intelligence

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

Annotations already declare read-only, idempotent, non-destructive, closed-world behavior, so the safety bar is covered. The description adds genuinely useful behavioral context beyond them: what the score is computed from (HHI over partner-country shares), that a China-exposure read is returned, and that tier gating changes output depth (free = risk band only; Pro = score and drivers).

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 tightly packed sentences: the usage trigger is front-loaded, then the method, then the tier-behavior caveat. No filler and 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 an output schema present, return-value detail is not required, yet the description still discloses tier-dependent output depth. Purpose, trigger conditions, method, and safety profile are all covered for a single-parameter read-only 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 description coverage is 100% and there is only one parameter, so the schema already documents that commodity accepts a name, partial name, or HS6 code. The description adds domain scoping (critical minerals, rare earths, battery materials) but no additional input syntax or format detail, making 3 the appropriate baseline.

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

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

States a specific verb+resource (scores supply concentration risk) and names the exact method (Herfindahl-Hirschman index over partner-country shares) plus the China-exposure read. This clearly separates it from siblings like screen_suppliers, get_commodity_snapshot, or search_trade_flows, which do not produce a computed concentration score.

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 explicit trigger conditions: supply-chain risk, China dependence, supplier concentration or diversification for a critical mineral, rare earth or battery material. It does not, however, name a sibling tool or state when NOT to use this (e.g., for a plain commodity profile use get_commodity_snapshot), so routing is good but not fully disambiguated.

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 behavior, so the safety profile is covered. The description adds real value beyond that: it enumerates what the brief contains (trade position/momentum, scored concentration risk, corridor breakdown, primary-vs-secondary feedstock) and discloses a "Pro tier only" entitlement gate.

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

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

Two sentences, zero waste: the first front-loads the usage trigger, the second enumerates report contents, and the tier restriction is tacked on at the end. Everything is load-bearing.

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?

An output schema exists, so return structure need not be explained, and the description covers purpose, content, and the Pro-tier requirement. It stops short of noting alternatives or fallbacks for non-Pro callers, which is a minor gap for a single-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 description coverage is 100%, so the baseline is 3. The description goes slightly beyond the schema's "Commodity name, partial name, or HS6 code" by constraining the domain to a single tracked critical mineral, rare-earth oxide, or scrap stream — useful scoping, though it adds no format or syntax detail.

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 (generate) and resource (a complete sourcing/procurement brief) scoped to one tracked commodity. It clearly distinguishes itself from siblings like get_commodity_snapshot, assess_supply_risk, list_reports, and read_report by describing the composite deliverable it produces.

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 this when the user wants a complete sourcing or procurement brief for one tracked critical mineral, rare-earth oxide or scrap stream" gives clear triggering context and input scope. However, it does not name alternatives or exclusions (e.g., when to prefer get_commodity_snapshot or assess_supply_risk instead), so routing is only partly guided.

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 bar is lower; the description still adds real behavioral value by disclosing the return shape (period covered, imports, exports, net position, lead partner) and a tier-gated capability difference for Pro. It does not mention units, coverage windows, or behavior when a commodity is ambiguous, so it is good but not exhaustive.

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 carrying distinct payload: trigger, examples, return contents plus tier note. The use case is front-loaded and there is no filler or restatement of the tool name.

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?

An output schema exists, so return-value documentation is not strictly required, yet the description still summarizes the payload. Combined with full schema coverage and a complete annotation set, an agent has enough to call this correctly; only minor operational details (units, period format, ambiguous-commodity handling) are absent.

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 baseline is 3, but the description goes further by giving concrete commodity examples (branded product names like nickel MHP, NdPr oxide) that show what a valid

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 ('quick picture of the trade position or main source countries for a critical mineral') and grounds it with concrete examples (lithium carbonate, cobalt hydroxide, nickel MHP, NdPr oxide). It also enumerates the returned fields, so the agent knows exactly what this tool produces. It does not explicitly contrast itself with the sibling search_trade_flows, which is the main remaining gap.

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?

Opens with an explicit trigger ('Use this when the user wants a quick picture...'), giving clear when-to-use context for the exploratory/summary case. The closing note that Pro 'adds the full partner-country breakdown with shares' implicitly signals the boundary against a deeper trade-flow search, but no alternative tool is named or excluded outright.

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

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

Annotations already declare read-only, idempotent, non-destructive and closed-world, so safety needs no restating. The description adds genuinely new behavioral context: results are reviewed patent families and counts are floors for recent Indian-office filings, a data-completeness caveat not available in the schema or annotations.

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

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

Three sentences, front-loaded with the trigger condition and closing with exclusions. The middle sentence is dense with illustrative examples, which aids recognition but runs slightly long; nothing is wasted.

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

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

An output schema exists, so return structure need not be described. The description covers scope, filtering, and the important data caveat that counts are floors for recent Indian-office filings, leaving no material ambiguity for a read-only query 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 description coverage is 100%, so all four parameters are already documented with ranges, enums and defaults. The description restates the stage and Indian-applicant filters without adding syntax or format detail beyond the schema, matching the baseline for high-coverage schemas.

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 — lists reviewed patent families for one critical mineral — plus concrete domain examples (lithium extraction, rare-earth separation, battery recycling). It clearly differentiates from siblings like verify_patent_provenance and track_rd_project_ip by scoping itself to patent families per mineral.

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 states when to use it ('user asks about patents, inventions or processing technology for a critical mineral relevant to India') and when not to ('Do not use for patent legal status or for trade or price questions'). The exclusions route the agent away from search_trade_flows and provenance-checking 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 safety bar is low. The description adds genuinely useful behavioral context: the underlying data sources (SATYABHAMA Ministry of Mines S&T, JNARDDC projects) and the granularity limit ('mineral-level counts only, not record-level links'), which prevents wrong expectations about drill-down.

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 trigger, then data sources, then the granularity caveat and the default-scope note. Every sentence carries information, though the parenthetical source listing is slightly dense.

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?

An output schema exists, so return format needs no explanation. The description covers purpose, triggers, data provenance, scope/granularity, and the default-argument behavior — everything an agent needs to call it correctly.

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

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

Schema description coverage is 100% and the mineral id enumeration is already in the schema, so the baseline is 3. The description adds meaning beyond it by documenting the default behavior when mineral is omitted (compare all), which the schema does not state.

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 analytical verb+resource: comparing patent families against funded R&D projects per India-list critical mineral to surface technology gaps. It is clearly distinguishable from siblings like get_mineral_patents (patents only) and track_rd_project_ip by naming the gap-analysis output.

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 user-intent triggers ('where are technology gaps', 'patents but little funded R&D or the reverse', 'collaboration opportunities') and explains the no-argument case ('Omit mineral to compare all'). It does not explicitly name which sibling to prefer or when to avoid this tool, so it stops short of a 5.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds real behavioral context beyond that: the result set is deliberately capped at 15 commodities with monthly trade data, and it discloses the boundary condition that the website supply models cover 65 minerals while patent questions leave this tool entirely. It does not cover pagination or error behavior, but neither applies meaningfully to a fixed 15-item enumeration.

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 usage trigger and routing guidance are front-loaded before the enumeration, which is the right ordering. The parenthetical commodity list is long but earns its place because callers must pass subsequent tools a commodity name, and this is the authoritative source of valid names. Slightly heavy for a single-tool read, hence 4 rather than 5.

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?

An output schema exists, so return values need no prose, yet the description still tells the agent what the payload will contain and how it is grouped (primary mined/refined vs secondary scrap/recycled, plus HS codes). Combined with the explicit scope boundaries against the supply models and CM-PATRA tools, an agent has everything needed to call this correctly 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?

The tool takes zero parameters, so per the rubric the baseline is 4. The description sensibly spends no effort on parameter syntax and instead uses the space for scope and routing context.

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 (lists the 15 tracked commodities) and enumerates exactly what the list contains, including the primary/secondary split and HS codes. It explicitly demarcates its own scope from siblings: 'these 15 are the scope of the trade, risk and sourcing tools', with patents routed to CM-PATRA and 65 minerals belonging to the website models.

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 an explicit trigger ('when the user asks which critical minerals... MiningBridge covers') and an explicit pre-condition ('before any other MiningBridge tool if unsure of the commodity name'). It also names the alternative destination for a related question class (patent questions go to CM-PATRA tools), so the agent has both when-to-use and when-not-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 declare read-only, idempotent, non-destructive behavior, so the bar is lower. On top of that the description adds domain-relevant traits: reports show published/free status and structural briefs are free. It does not mention pagination, result volume, or ordering, but the added coverage and pricing context exceed what annotations provide.

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 usage trigger is front-loaded and the filter and status information follows logically. The long enumeration of individual minerals is arguably bloat, but it does help the agent judge topical relevance across many possible queries, so it mostly 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, return values need not be explained, and the description correctly focuses on scope, filters, and free/published status. It is nearly complete; the only gap is absence of explicit disambiguation from the closely related report-reading and report-generating siblings.

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 two enums, so the schema already documents all four parameters. The description's 'Filter by commodity, depth band or criticality list' largely restates the schema, and its note that structural briefs are free slightly tensions with the schema's "'brief' is free" wording, so it adds only marginal meaning over 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?

The description gives a specific verb ('Lists') and a clearly scoped resource ('MiningBridge research reports'), plus the coverage domain (65 minerals across the US 2025 and India 2023 lists). It does not, however, explicitly distinguish itself from siblings like read_report or generate_market_report, so the agent must infer the boundary.

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 opens with a concrete when-to-use trigger ('when the user asks about the supply chain, mining, processing... of a critical mineral'), which is strong routing context. It stops short of naming alternatives or when-not-to-use conditions (e.g., versus read_report for a single known report), so it is clear but not fully exclusive.

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=false, so safety is covered; the description adds genuinely new behavioral context by disclosing entitlement-gated returns (full text vs. opening section plus contents list) and that briefs are always free. It does not mention rate limits or pagination, which is the only remaining 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?

Two sentences, front-loaded with the sequencing instruction, and the topical scope is compressed into a single clause. The subject-matter listing is on the long side but is doing real selection work for the agent.

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, return-value detail is unnecessary, and the description still covers the non-obvious part of the response — the two entitlement tiers. Precondition, scope, and access behavior are all present for a one-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?

Schema description coverage is 100% and the single 'slug' parameter is documented in the schema with an example, so the baseline of 3 applies. The description adds no syntax or format detail beyond what the schema already provides.

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

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

States a specific verb and resource ('read a MiningBridge report') and immediately scopes the subject matter (critical minerals/rare earths, mining, refining, export controls, end uses). The opening clause 'Use this after list_reports' separates it cleanly from its nearest sibling, 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?

Gives an explicit sequencing rule ('Use this after list_reports'), which is the exact condition that selects this tool over list_reports or the other research siblings. No exclusions are needed because the precondition fully determines usage.

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/destructive-free and closed-world, so the safety profile is covered. The description adds genuinely new behavior: Free tier yields only match counts and jurisdictions, while Pro yields named entities with contact channels — that materially affects how results should be interpreted. No pagination or rate-limit detail, hence not 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?

Three sentences, no filler: trigger context first, capability second, tier-dependent output third. Every sentence 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 an output schema present, return values need no explanation, and the description covers use-case, inputs, and tier behavior. The one gap is that zero parameters are required, yet the description never says what a call with neither query nor country returns.

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 both parameters are self-documenting with their own examples. The description's country examples and "by country or free-text query" framing largely restate the schema, so baseline 3 applies; it adds no syntax, format, or combination guidance.

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 (screens) and resource (MiningBridge counterparty directory) with concrete scope: miners, refiners, processors, recyclers, traders of critical minerals, by country or free-text. The entity set and data source make it plainly distinguishable from siblings like search_trade_flows or get_commodity_snapshot.

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 this when the user is looking for miners, refiners..." gives a clear triggering context with examples of jurisdictions. There are no explicit exclusions or named alternatives, so it stops short of a 5, but an agent knows when to reach for 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 establish readOnly, idempotent, non-destructive, closed-world behavior. The description adds genuinely new context: results are individual claims each carrying a publisher, so figures can be checked and cited, which tells the agent about granularity and provenance of results.

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

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

Front-loaded with the trigger condition ('Use this when...'), followed by scope, result nature, and exclusion. Three sentences, all earning their place, no 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?

With an output schema present, return formatting need not be explained, and annotations cover the safety profile. The description covers trigger, scope, and result granularity well; only minor operational details (result limits, pagination, how multiple minerals combine with query) are unaddressed.

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

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

Schema description coverage is 100%, so both the free-text query and the mineral slug are already documented in the schema with matching examples. The description adds no new syntax, matching behavior, or filter-combination guidance beyond what the schema provides.

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

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

States a specific verb (search) and resource (individual sourced claims in the evidence base) and enumerates the exact topical domains (production, processing/refining capacity, export controls, country concentration). This is clearly distinguishable from siblings like get_commodity_snapshot or search_trade_flows.

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 explicit when-to-use with three concrete example queries and a clear when-not ('Do not use for live prices or investment advice'). It does not name the sibling tools that should be used instead, so the routing is 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), and the description adds genuinely new operational context: the UN Comtrade source, the one-commodity scope, and the tier-gated result window (Free = trailing three months, Pro = full series). It stops short of stating auth requirements or pagination behavior.

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

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

The usage trigger is front-loaded in the first clause, followed by return scope, tier limits, and the exclusion in descending order of importance. No sentence is redundant or padded.

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?

An output schema exists, so return values need no elaboration; the description covers everything else an agent needs to select and call it correctly - data source, geographic scope, commodity cardinality, result-window limits, and an explicit negative case. Nothing material 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 description coverage is 100%, including the flow enum and commodity format example ('lithium', 'NdPr', '283691'), so the schema already carries the parameter burden. The description only implies flow selection via 'import or export' and adds no syntax or format detail 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?

States a specific verb+resource combination ('Returns US monthly import or export values (UN Comtrade) for one tracked commodity') and names the data source, so the agent knows exactly what class of answer it produces. It also carves itself away from price-oriented siblings with the explicit 'Do not use for spot or futures prices.'

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 an explicit trigger in user-intent terms ('when the user asks how much ... is being imported or exported, or how trade volumes are trending month to month') and an explicit exclusion (spot/futures prices). Both the when and the when-not are present, so no inference is needed.

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 only cover the safety profile (readOnly, idempotent, closed-world), while the description adds real behavioral substance: the returned fields, the two-tier candidate ranking rule, and an explicit disclaimer that candidates are not verified outcomes. That reliability caveat is exactly the kind of context annotations cannot carry.

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 trigger, followed by the ranking rule and disclaimer in dense but purposeful sentences. Slightly heavy; the identifier examples appear in both the description and the schema, which is mild 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?

An output schema exists so return values need not be explained, yet the description still summarizes what is returned and, more importantly, discloses the candidate-matching heuristic and its uncertainty. Nothing needed to call or interpret this tool 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 description coverage is 100% and the single parameter already documents the same example formats the description repeats. The description adds no syntax or matching-semantics detail beyond the schema, 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?

States a specific verb+resource ('track an R&D project' with the patent linkage) and pins the domain to Indian public R&D projects. It is clearly separable from siblings like get_mineral_patents or verify_patent_provenance, which do not resolve a project record.

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 an explicit trigger ('Use this when the user asks about a specific Indian public R&D project') and enumerates accepted identifier forms (SATYABHAMA SNTMOM numbers, JNARDDC/S-58, title words). It does not state exclusions or name an alternative for the related-but-different patent queries, 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 establish read-only, idempotent, non-destructive, closed-world behavior, so the bar is lower. The description adds genuine value beyond them by disclosing a scope limitation ('Legal status is not held; the result links to where it can be checked'), telling the agent what data will be absent and how to pursue it further.

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 usage trigger before the detail. Every clause earns its place: the returned fields, the source links, and the legal-status caveat all add information with no padding.

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 lookup, the description covers the trigger, the returned content, and a key data limitation, while annotations supply the safety profile and an output schema covers return structure. Nothing an agent needs to call this correctly 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?

There is one parameter with 100% schema description coverage ('Publication number or CM-PATRA record id.'), so the schema already carries the semantics. The description adds nothing about accepted identifier formats or what happens on an unknown id; baseline 3 applies when the schema does the heavy lifting.

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 (verify/check) and a precisely scoped resource: one patent family in CM-PATRA, enumerating what is returned (mineral/processing-stage labels, CPC codes, applicants, filing offices, source links). The singular 'one patent family' implicitly contrasts with the listing sibling get_mineral_patents, but no sibling is named explicitly, so it stops short of full differentiation.

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 this when the user wants to check one patent family in CM-PATRA' gives a clear, explicit trigger condition. There is no when-not guidance and no named alternative (e.g. get_mineral_patents for bulk listing), which keeps it below a 5.

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