Ni Biashara Shelves — Africa FX, freight & compliance checks (x402)

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

No annotations, so the description carries the full burden — and it does real work: it discloses the three return fields (x402_url, pay_url, claim_url) and, critically, "Does not move money itself," which tells the agent this is a checkout-creation step, not a charge. Gaps remain on auth requirements, idempotency, and link expiry, which matter for a paid checkout tool.

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

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

Three short sentences, no waste, with the escape-hatch condition front-loaded before the return values and the non-mutation caveat. 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?

For an 18-parameter generic checkout tool with no output schema and no annotations, the description covers the essentials: selection rule, return shape, and the money-movement caveat, while per-SKU parameter scoping is delegated to a fully documented schema. It stops short of covering failure modes or payment flow details an agent might need.

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 each of the 18 parameters already documents which SKU it belongs to (e.g., address for sanctions-wallet-screen, license_line for tx-insurance-ce-check). The description adds no parameter-level meaning 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 concrete verb+resource ("Creates a Coinbase checkout for any SKU") and frames the tool's role as the generic fallback, which separates it from the fifteen-plus job-named siblings like vet_load, check_carrier_authority, or get_fx_official. An agent can tell instantly whether this is the right tool or whether a specific one exists.

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 no job-named tool exists" is an explicit routing rule, including an implicit when-not-to-use (a named SKU tool exists). It does not name list_shelves as the discovery path or the specific sibling examples, but the selection logic itself is 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?

Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the agent knows this is a safe read operation. The description adds substantial behavioral context beyond annotations: it explains the payment flow (402 → PAYMENT-SIGNATURE → delivery), that the tool call itself is free, that payment is $0.99 USDC on Base, and that the pass token travels via the X-SHELF-PASS header. It does not mention credit expiration or rate limits, but the added transparency is strong.

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 dense but well-structured: it front-loads the price and credit value, then explains eligibility, payment method, and return value in logical order. Every sentence carries useful information, though the total length is on the longer side for a simple purchase tool, with minor redundancy in repeating the cost.

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 zero parameters, no output schema, and annotations covering safety, the description is nearly complete for an agent to call it correctly. It explains the return value (an x402 URL to GET), the payment flow, and the pass details. One minor gap is that it does not state what happens after credits are exhausted or whether the pass expires, but this is not critical for invoking the 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 tool takes zero parameters, so there are no parameter semantics to document. Per the scoring rules, a tool with no parameters receives a baseline of 4, which is appropriate here since the description correctly focuses on the purchase mechanics rather than inputs.

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 purchases a Shelf Pass — 110 prepaid credits for $0.99, and explains the credit-to-cost ratio. It distinguishes itself from a generic purchase by detailing the eligible shelves, though it does not explicitly compare against the sibling 'buy_shelf' tool, leaving a small gap in sibling 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?

The description lists the specific shelves the pass is valid for (FX, carrier, broker, sanctions checks, etc.) and notes the $0.25 price cap, which implies when the pass is useful. However, it does not explicitly say when to use this tool versus alternatives like 'buy_shelf' or paying per call, nor does it provide clear exclusions or a decision rule.

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?

Beyond the readOnly/openWorld annotations, it discloses the entire execution model: $0.03 USDC on Base, the x402 handshake (402 → PAYMENT-SIGNATURE → delivery), that the tool call itself is free, and that payment occurs on the returned URL. That is exactly the non-obvious behavioral context an agent needs before committing.

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 resource and the question it answers, then price and payment mechanics. The title is restated verbatim in the first sentence and 'Free to call this tool; payment happens on the URL' slightly restates the preceding x402 sentence, minor 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 single-parameter, no-output-schema tool, it covers return shape ('returns the x402 URL to GET'), the payment sequence, and the decision context. An agent would not need anything else to invoke it and complete payment 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?

Only one parameter exists and schema coverage is 100%, so the schema already documents 'mc' as the MC/docket number. The description repeats that identity but adds no format guidance (e.g. numeric-only vs 'MC' prefix), so it adds little beyond structured data.

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

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

States a concrete verb and resource: a live FMCSA broker-authority lookup keyed by MC/docket number, framed as 'Is this broker real and allowed to arrange freight?' The broker-vs-carrier split is clear from the wording, which implicitly separates it from check_carrier_authority, though that sibling is never named as a contrast.

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 check a carrier or factoring agent runs before accepting a load from an unknown broker' gives a clear usage situation and audience. It stops short of explicit exclusions or pointing to alternatives such as check_carrier_authority or vet_load when the entity is a carrier rather than a broker.

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?

Goes well beyond the readOnly/openWorld/destructive annotations by disclosing cost ($0.03 USDC on Base), the payment protocol (x402: 402 → PAYMENT-SIGNATURE → delivery), and clarifying that invoking the tool itself is free while payment occurs against the returned URL. That economic and side-effect context is exactly what annotations cannot convey and prevents an agent from treating this as a free direct data call.

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 definition and field list, then pricing and protocol mechanics. Dense but nearly every clause carries information; the em-dash field enumeration is efficient. The payment flow sentence could be tightened but nothing is 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?

No output schema exists, so the description correctly carries the return burden by listing the fields and clarifying that the immediate return is an x402 URL rather than the carrier record itself. Failure modes (invalid MC/DOT, carrier not found) are unaddressed, which is the main remaining gap.

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

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

Schema description coverage is 100% and both parameters (mc, dot) are documented as interchangeable identifiers with the 'this or dot required' constraint already stated in the schema. The description adds nothing about identifier formats or precedence, 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 and resource ('Live federal FMCSA record for a US motor carrier') and enumerates the returned fields — legal name, operating status, authority, safety rating, fleet size, crash/inspection summary, risk flags. An agent knows exactly what it gets. It does not, however, distinguish itself from close siblings check_carrier_basics or vet_load, leaving overlap unresolved.

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?

Provides a usage trigger — 'the check a freight-broker or dispatch agent runs before tendering a load' — which is real context. But it names no alternatives (check_carrier_basics, check_broker_authority, vet_load) and gives no exclusion or prerequisite guidance, so the agent must infer which of several near-identical vetting tools to pick.

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?

Beyond the readOnly/openWorld annotations, it discloses the paid flow in detail: $0.03 USDC on Base, calling the tool is free, the return value is an x402 URL to GET, and the sequence is 402 → PAYMENT-SIGNATURE → delivery. It also discloses a real data caveat (percentiles/threshold alerts are null for freight carriers), which is exactly the kind of behavior an agent needs before calling.

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 what the data is, then caveats, then pricing and mechanics — order matches the agent's decision flow. It is dense but nearly every sentence carries information; the pricing sentence is slightly compressed ('402 → PAYMENT-SIGNATURE → delivery') but still readable.

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

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

With no output schema and a single required param, the description supplies everything else the agent needs: what data comes back, what can be null, that calling is free, and how payment and delivery work. Nothing material is missing for correct invocation.

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?

Only one parameter (dot) with 100% schema description coverage, so the schema already carries the semantics. The description adds nothing about USDOT format or validation, making this baseline 3 under the coverage rule.

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

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

It names a concrete resource (FMCSA SMS BASIC measures) and enumerates what's inside: unsafe driving, hours-of-service, vehicle maintenance. The content is clearly distinguished from check_carrier_authority via the 'Complements...' line, but the tool's own action is nominal (a noun phrase) rather than a verb, so it's clear but not maximally crisp.

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

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

Usage is implied by 'Complements carrier-authority-check', suggesting it is used alongside authority lookups, and the freight/passenger caveat tells the agent what data will be populated. However there is no explicit 'use this when' / 'do not use this when' statement or a named alternative for related safety checks.

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, non-destructive, open-world access, so the safety profile is covered. The description adds genuinely new behavior: the three possible outcome states (listed / possible_match / not_listed) and that each match carries an id and a nibiashara.com/b/<id>/ page URL. It does not state rate limits or what an empty result looks like in edge cases, keeping it short of a 5.

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

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

Three short sentences, front-loaded with the cost marker and the core question the tool answers. The return-shape sentence is compact and no sentence is redundant.

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

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

With no output schema, the description helpfully enumerates the return states and the match payload (id plus URL), which the agent could not otherwise know. The remaining gap is that required parameters are zero, so it never states that at least one of name or phone must be supplied for a meaningful lookup.

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

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

Schema coverage is 100%, so all three parameters (name, metro, phone) are already documented in the schema, including the 'this or name' alternation. The description only restates that you search by name or phone with optional metro, adding no format or normalization guidance beyond the schema. 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?

States a specific verb ('Look up') and resource (African/Caribbean diaspora business in the Ni Biashara directory) and names the source domain. No sibling tool covers directory lookups, so it is trivially distinguishable from buy_shelf, screen_sanctions_name, or the FX 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?

Gives clear calling context: 'Look up by name or phone, optionally by metro,' plus the 'Free' marker that signals no cost barrier. It does not name exclusions or an alternative tool, but no sibling overlaps this function, so the missing routing guidance costs little.

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?

Goes well beyond the readOnly/openWorld/non-destructive annotations by disclosing that output is deterministic rules-engine results rather than an LLM guess, the exact cost ($0.25 USDC on Base), and the full x402 handshake (402 → PAYMENT-SIGNATURE → delivery). This is exactly the non-obvious operational 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-loads purpose in the first sentence and then layers justification, payment, and return mechanics with no filler. Slightly dense — the title restatement opening and the payment sentence compete for attention — but every sentence carries information.

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

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

With no output schema, the description correctly compensates by explaining what is returned (the x402 URL to GET) and what the payload contains. It leaves minor gaps such as behavior on an unsupported license_line value or response format after payment, but an agent has enough to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters fully, including the license_line vocabulary and the 0-40 integer range. The description only echoes 'by license line and years licensed' without adding format or defaulting nuance, 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?

Names a specific check (CE & renewal compliance) on a specific resource (Texas insurance license, TDI rules) and enumerates the outputs — CE hours, classroom/ethics requirements, renewal fees — by license line and years licensed. An agent can distinguish it from sibling check_tx_realestate_ce purely on domain without opening either 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?

Provides clear context for invocation: it is a deterministic rules-engine lookup scoped by license line and years licensed, and it explicitly states that calling the tool is free and the $0.25 payment happens on the returned URL. It does not name when-not-to-use or an alternative sibling (e.g. when to prefer a general TDI lookup), so it stops short of full when/when-not routing.

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

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

Goes well beyond the readOnly/openWorld annotations: it discloses that output is a deterministic rules-engine result rather than an LLM guess, the price ($0.25 USDC on Base), and the exact x402 call flow (402 → PAYMENT-SIGNATURE → delivery). The crucial clarification that calling the tool itself is free while payment occurs on the returned URL removes real ambiguity.

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 purpose, then determinism, price, and payment flow; every sentence is informative. Slight redundancy between the pricing sentence and 'Free to call this tool; payment happens on the URL', but it is short and scannable.

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 only two fully-documented params and no output schema, the description supplies what an agent needs to invoke it, including what is returned (the x402 URL to GET) and the payment mechanic. It could add a note about the payload returned after payment, but nothing critical 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%, so the schema already documents license_type and first_time values, and the description's 'by license type' adds no syntax beyond it. Baseline 3 applies when the schema carries the parameter burden.

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+resource+scope: TREC continuing-education hours, renewal fees, and active-license requirements for Texas real-estate licensees, filtered by license type. It clearly distinguishes itself from the adjacent check_tx_insurance_ce sibling by domain (real estate vs insurance).

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 domain scope ('for Texas real-estate licensees, by license type') implies when to use it, but there is no explicit when-to-use/when-not statement and no named alternative. An agent must infer that check_tx_insurance_ce is the sibling for insurance lines rather than real estate.

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 cover the safety profile (readOnly, non-destructive), and the description adds substantial behavior beyond that: it is a floor estimate, unpublished charges are listed rather than guessed, prohibited/restricted items return estimate_available:false with a reason code, data vintage (rates retrieved 2026-10-19), and non-affiliation. This is exactly the extra disclosure a caller needs for a pricing tool.

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

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

Front-loads the key fact ('Free.') and keeps most sentences load-bearing. There is mild redundancy in stating the direct-booking relationship twice ('Links to book and pay Doos directly' and 'You book and pay Doos Logistics directly'), which costs it a point.

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 12-parameter, no-output-schema tool, the description covers the estimate's nature, the prohibited/restricted result shape, the no-payment contract, and data provenance. It does not sketch the successful estimate payload (fields returned for a priced item), which is the one remaining gap.

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

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

Schema description coverage is 100%, so parameters like weight limits, enum-like item_category values, and the 24-inch volume-charge rule are already documented in the schema. The description adds only marginal semantic value by naming liquid/perishable/hazmat as the no-price categories, which is baseline territory.

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 precise verb+resource: a floor air-shipping estimate from Doos Logistics' Fort Worth hub to Lagos, built only from published rates. It is clearly distinguishable from sibling tools like prepare_us_nigeria_shipment_handoff because it repeatedly frames itself as an estimate only ('No payment: this tool returns the estimate itself').

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

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

Gives clear exclusions ('Ocean not offered') and a boundary with the booking flow ('No payment', 'You book and pay Doos Logistics directly'), which implies the handoff tool handles purchase. It never names a sibling tool as the alternative to use, so it stops short of explicit routing, but the context is 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?

Annotations already declare readOnly/openWorld/non-destructive, and the description adds substantial context beyond them: values are computed live at call time, they are directory counts rather than census data, and the paid x402 flow is spelled out ($0.02 USDC on Base, tool call free, GET the returned URL and handle 402 → PAYMENT-SIGNATURE). The payment-flow sentence is cryptic but directionally useful.

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 what, then scope, then the counts-only caveat, then pricing/payment mechanics. The opening clause echoes the title, but no sentence is filler and the ordering prioritizes what an agent needs first.

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

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

With no output schema, the description does explain the returned content (counts by metro and by category with contact-field coverage) and that the immediate return is an x402 URL. Slightly thin on the exact response shape, but sufficient to call correctly.

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

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

Schema coverage is 100%, so a baseline of 3 applies. The description still adds semantics the schema does not: both filters are optional and combining or omitting them changes scope ('metro and/or category, or omit both for the whole directory').

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: counts of African/Caribbean diaspora business listings in the Ni Biashara directory, broken out by metro and category, with contact-field coverage. The line 'Counts only, no business-level fields' implicitly separates it from the business-level sibling check_diaspora_business_listing, though it never names that sibling.

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?

Covers in-tool usage ('Filter by metro and/or category, or omit both for the whole directory'), which tells an agent how to scope a call. It gives no explicit when-to-use-this-vs-alternative guidance and names no sibling, so selection between this and check_diaspora_business_listing must be inferred from 'counts only'.

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 readOnlyHint=false, the description explains why: it spends $0.1 USDC on Base or credits from a valid Shelf Pass, with a specific ≤$0.25 shelf-ceiling rule and a note that the token is not spent above the ceiling. It also discloses the failure mode (payment_required with x402 v2 URL and header name), which annotations alone would not convey.

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

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

Front-loaded with the resource and scope, then pricing and auth behavior. The closing sentence ("It does not return the rate as a bare payment link") is a slightly awkward negative framing but still earns its place as a disambiguation.

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

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

No output schema, so the description carries the burden and does supply return shape (rows carry source and time; spreads included) and the alternate payment_required response. Complete enough for an agent to know what it gets and what it costs, though it doesn't describe pagination or row volume.

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

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

Schema coverage is 100% so the baseline is 3, but the description adds real meaning beyond the schema for the single pass_token parameter: it names the accepted header (X-SHELF-PASS), the ceiling condition, and the credit-spend consequence -- context the schema hints at but doesn't fully quantify.

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

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

States a concrete resource (the full African FX brief: Frankfurter official pairs plus Bybit-derived street quotes and spreads) and its scope, which distinguishes it from the narrower single-source siblings get_fx_official and get_fx_parallel. It doesn't name those siblings, so the differentiation is implied rather than explicit.

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

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

"One call for a morning pricing check" gives implied usage, and the payment path (Shelf Pass required above/below ceiling) is spelled out. But it never says when to use this composite brief versus calling get_fx_official or get_fx_parallel, nor any exclusion conditions.

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 are sparse (readOnlyHint=false, openWorldHint=true, destructiveHint=false), and the description carries the burden well: it discloses pricing ($0.01 USDC on Base), the Shelf Pass ceiling (≤$0.25) above which credits are not spent, the x402 v2 payment_required fallback, and the source-blend caveat plus as_of/fetched_at fields. This is rich behavioral disclosure consistent with readOnlyHint=false.

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

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

Front-loaded with the core purpose and currency list, then payment mechanics, then a useful negation ('does not return the rate as a bare payment link'). Dense but every sentence mostly earns its place; the title repeated as the opening sentence is minor 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?

No output schema exists, and the description compensates by naming the response fields (source, as_of, fetched_at) and the payment-failure shape. It is nearly complete for a paid single-pair fetch, though it omits error behavior for an unsupported/invalid pair.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine meaning: the pass ceiling rule ('above the pass ceiling the token is not spent') and the pricing context that gives the pass_token parameter its purpose. The pair format itself is only in the schema, so it isn't a full 5.

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

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

The description states a specific verb, resource and scope — the official USD reference rate for exactly one African currency — and enumerates the supported currencies (KES, NGN, GHS, TZS, UGX, ZAR, EGP, RWF). The word 'official' plus the blend-vs-fixing clarification cleanly separates it from the sibling get_fx_parallel without opening either 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?

It explains the payment/eligibility conditions under which data is returned versus a payment_required response, which is real usage context. However, it never tells the agent when to prefer this tool over get_fx_parallel or get_fx_africa_brief; the distinction is left to be inferred from 'official'.

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 mark it readOnlyHint=false, and the description justifies that by disclosing the $0.05 USDC on Base cost, the pass_token credit-spend behavior, the ceiling rule (token not spent above the ceiling), and the exact non-success return shape (payment_required with x402 v2 URL and header name). This is far more than the annotations convey and materially useful.

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 resource and methodology, and every clause carries information. Slightly dense, and the trailing 'It does not return the rate as a bare payment link' is marginally redundant, costing it a point.

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

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

With no output schema, the description still covers both return paths (the data, or payment_required with the x402 v2 URL), the price, and the pass eligibility rule. An agent has everything needed to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning about pass_token: it is spent only on an eligible shelf and not spent above the ceiling, which clarifies the parameter's side effect beyond the schema text.

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

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

States a specific resource and scope: the street/parallel-market rate for USD-NGN or USD-GHS, with the exact methodology (median VWAP of Bybit's USDT/fiat P2P book ÷ USDT/USD spot basis, plus Frankfurter official reference). It also carves out what it is not (central-bank rate, bureau de change quote), which lets an agent distinguish it from the get_fx_official sibling.

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 clear context for when this applies versus an official rate, and spells out the payment/eligibility conditions (valid Shelf Pass on a shelf priced ≤ $0.25 versus falling back to payment_required). It does not explicitly name get_fx_official as the alternative, so the routing is implied rather than stated.

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

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

With no annotations, the description carries the behavioral burden and does well by disclosing the conditional delivery behavior and the Coinbase payment COMPLETED prerequisite. It does not cover error cases such as invalid claim_secret or list possible status values, but the main behavior is transparent.

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

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

Two sentences, front-loaded with the core return behavior and followed by the important claim_secret condition. There is no wasted text.

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

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

The description covers the two main invocation modes and the payment-completion gate, which is enough to call the tool. However, with no output schema and no annotations, it could do more to describe response shape, possible status values, or error behavior for an invalid claim_secret.

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

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

Schema coverage is 50%, and the schema already explains that without claim_secret only status is returned. The description adds useful context that claim_secret is returned once when the order opens and gates delivery on payment completion, but order_id remains self-evident and undocumented.

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: it returns order status, and with claim_secret includes delivery. This is clear, though it does not explicitly differentiate from any sibling because no sibling overlaps this order-specific resource.

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

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

It clearly explains the key usage condition: without claim_secret only status is returned, and with claim_secret the delivery is included once payment is COMPLETED. It does not name alternatives or explicit exclusions, but for this tool the main conditional is covered.

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 full burden of behavioral disclosure. It mentions 'Free' (a cost attribute) and instructs to pass a token, but it does not state that the operation is read-only, has no side effects, or what happens on invalid tokens. The behavioral profile is largely undisclosed.

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 very short but not well-structured. The standalone 'Free.' adds little value and the phrase '/shelf/shelf-pass-100' is cryptic. It is under-specified rather than efficiently concise, and the main purpose is not 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?

With no output schema and no annotations, the description should explain enough to invoke the tool correctly. It provides the token source but omits the return value, error behavior, and confirmation that the operation is safe. For a simple one-parameter tool this is still a notable gap, though the title partially covers the expected 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 schema already describes the token as a 'pass_… token' with 100% coverage, so the baseline is 3. The description adds the source of the token ('from buy_shelf_pass /shelf/shelf-pass-100'), which is helpful context. However, the endpoint path is cryptic and the instruction is terse, adding limited meaning 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 does not explicitly state that the tool checks a credit balance. It only says 'Free. Pass the token from buy_shelf_pass /shelf/shelf-pass-100.' This is an instruction, not a clear statement of the operation. The title provides the purpose, but the description itself fails to describe what the tool does.

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 gives a prerequisite (obtain token from buy_shelf_pass) but does not indicate when to use this tool versus its siblings. It does not mention alternative tools like check_broker_authority or check_carrier_authority, nor does it specify conditions or exclusions. The token-source hint is useful but not enough for selection decisions.

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?

There are no annotations, so the description carries the behavioral burden. It discloses that the tool is free to call, which is a useful cost-related behavior, and clarifies how the kind parameter changes the result set to include owner-fulfilled work. It does not mention auth, rate limits, or side effects, but the verb 'list' implies a read operation and the core behavioral traits are covered.

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 contain the essential information with no filler. The primary purpose and default behavior are front-loaded, followed by the optional parameter guidance and the free-to-call note.

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 one-parameter listing tool with no output schema and no annotations, the description is complete: it names the resource, what is returned, the optional parameter values and their effect, and the cost of calling. An agent can reasonably decide whether and how to invoke this tool without further clarification.

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 documents the kind parameter with an enum and a default of data, so the baseline is 3. The description adds meaning by explaining that service and all include owner-fulfilled work, which gives an agent a reason to choose one value over another beyond the raw 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 states a specific verb and resource: it lists shelves sold by Ni Biashara, with the default being data shelves. It also names the return contents (price in USD, params, job-tool name, x402 URL), which clearly distinguishes it from purchase-focused siblings like buy_shelf.

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 gives clear context for when to use it: to list shelves, with data as the default and service/all available via the kind parameter. It does not explicitly name alternatives or state when not to use it, but the context is sufficient for this simple listing tool.

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

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

Annotations cover safety (readOnlyHint, destructiveHint=false, openWorldHint), and the description adds substantial context beyond them: the model runs in-process, output is machine-grade and labeled as such, cost is $0.25 USDC on Base, and the delivery is an x402 URL flow (402 → PAYMENT-SIGNATURE → delivery). This discloses pricing, quality tier, and settlement mechanics that 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 core purpose and scope, then layered detail on quality, price, and payment. It repeats the title verbatim as its opening sentence and slightly restates the "machine" nature, which is mild redundancy, but every section is relevant and well-ordered.

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

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

With no output schema, the description carries the return burden and does so: it explains the paid response, the x402 URL to GET, and the 402/payment-signature handshake. Combined with the tier guidance and pricing, an agent has everything needed to invoke and interpret the result.

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

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

Schema coverage is 100%, so both params (text, direction) are already fully documented with the 120-word limit and en-sw/sw-en default. The description restates the word limit but adds no new syntax or format 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 (localize) and resource (English↔Swahili text) with a clear scope limit (up to 120 words), and explicitly distinguishes itself from the human-reviewed sibling swahili-localization-500w. An agent can tell this apart from the other shelf tools without opening any schema.

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

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

Gives explicit fit guidance ("Suited to UI strings, alt text and short product copy") and names the alternative shelf (swahili-localization-500w) with its condition (human-reviewed, up to 500 words). It also clarifies the payment model — "Free to call this tool; payment happens on the URL" — removing the biggest source of agent confusion.

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=true, destructive=false, openWorld=false), yet the description adds a lot: OFAC name screening, a 400 refusal for prohibited/hazmat, a 200 ask_doos_first path for restricted items with no price or booking links, the ready_for_doos path, the fact that it never books or takes payment, non-affiliation with Doos, and the rate retrieval date.

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 behavioral content is front-loaded well, but the text repeats itself: 'we never book or take payment' and 'You book and pay Doos Logistics directly' appear twice, and 'Free.' plus 'No payment: this tool returns the handoff itself.' restate the same point.

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

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

With no output schema and 14 parameters, the description must carry the return contract, and it does: it names the two statuses, states what is and is not included in each response (price, notices, booking links, checklist), and documents the 400 failure mode. Only the absence of explicit routing against the sibling estimate tool keeps it from a 5.

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 all 14 parameters, so the schema already documents units, defaults, ranges and enum-like value lists (e.g. item_category, delivery). The description only adds that both names are POSTed and are OFAC-screened, 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 states a specific verb and resource: it POSTs a US→Nigeria air shipment and both names, then returns a Doos Logistics handoff. That is far more than a restatement of the name. However, it never explicitly distinguishes itself from the sibling estimate_us_nigeria_shipping, so an agent must infer which of the two to call.

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

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

Usage is only implied: you POST the shipment and both names to get the handoff. The description describes branching outcomes (ask_doos_first vs ready_for_doos) but gives no when-to-use/when-not-to-use guidance and never names an alternative tool such as estimate_us_nigeria_shipping.

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?

Beyond the readOnlyHint/openWorldHint/destructiveHint annotations, it discloses the matching method (deterministic normalized-name and token matching), the freshness fields returned (as_of, checked_at), the verdict taxonomy (CLEAR/REVIEW/HIT), and the full x402 payment sequence (402 → PAYMENT-SIGNATURE → delivery, $0.02 USDC on Base). This is exactly the payment/semantics 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?

Purpose is front-loaded and every sentence carries information (dataset, verdict, cost, payment flow). The one inefficiency is the opening sentence duplicating the title verbatim, and the payment/URL mechanics are packed densely into the tail.

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

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

With no output schema, the description compensates by explaining what the agent gets back (x402 URL to GET, verdict, as_of/checked_at) and the full payment ceremony. Nothing needed to invoke or interpret the tool is missing for this scope.

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% for the single 'name' parameter, and the description adds no syntax or format detail (e.g. casing, ordering, alias handling) beyond what the schema already states. Baseline 3 is appropriate 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?

States a specific verb and resource — screens a company/entity name against the OFAC SDN and Consolidated lists — and quantifies the dataset (~40k names + aliases) and the verdict scheme. This is clearly distinguishable from the sibling screen_sanctions_wallet, which screens an address rather than a name.

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 when to use it (a name/entity screening task) and gives useful operational context ('Free to call this tool; payment happens on the URL'), but it never names an alternative or states a when-not condition. An agent must infer the name-vs-wallet split from the sibling list rather than being told.

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?

Goes well beyond the readOnly/openWorld annotations: discloses deterministic exact-match semantics (CLEAR or HIT), the absence of clustering/risk scoring, a concrete cost ($0.01 USDC on Base), and the full x402 payment flow (402 → PAYMENT-SIGNATURE → delivery) including that the tool call itself is free. This is substantive operational context an agent cannot infer from structured fields.

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

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

Front-loads the core action, then stacks the distinguishing details efficiently. Dense but each clause carries information; the title repetition at the start is the only 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?

Despite no output schema, the description explains the return shape (CLEAR/HIT verdict plus the x402 URL to GET) and the payment handshake, so an agent knows both the outcome and next step. Nothing needed to invoke it 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?

Schema coverage is 100% and the single 'address' parameter is already documented as 'digital currency address to exact-match (required)'. The description's 'exact-match a blockchain address' reinforces rather than extends that, so the baseline of 3 applies.

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

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

States a precise verb+resource: exact-match a blockchain address against OFAC Digital Currency Address identifiers from the SDN XML. It explicitly distinguishes itself from the name-screen sibling by noting it's 'the same Treasury list we ingest for name screens', so an agent can route address vs. name screens correctly.

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?

Clear context for when to use it (blockchain address screening against OFAC) and what it is not (no chain intel, no clustering, no risk score). It references the sibling name-screen use case but never explicitly instructs 'use screen_sanctions_name for persons/entities', leaving that routing implicit.

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?

Goes well beyond the annotations with genuinely operational detail: timeout sections return status "timeout" with partial:true and force a HOLD verdict, full price applies only when authority (broker for broker-only) is delivered, cost is $0.08 USDC on Base, and the x402 flow (402 → PAYMENT-SIGNATURE → delivery) is spelled out, including that the tool call itself is free and payment happens on the returned URL.

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 composite purpose, then scope, then failure/pricing semantics — a sensible ordering with no filler sentences. It is dense and slightly run-on (verdict acronyms and payment mechanics packed into one paragraph), but nearly every clause carries decision-relevant information.

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

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

With no output schema, the description correctly carries the burden of explaining returns: an x402 URL to GET, TENDER/HOLD/REJECT verdicts derived from public fields only (explicitly no fraud score), and the timeout/partial shape. The actual delivered payload structure is only implied, but the delivery mechanism and verdict vocabulary are enough for an agent to call and interpret it.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds the mapping between parameters and outputs — broker_mc runs the FMCSA broker-authority check, name drives the optional OFAC screen, and mc/dot are carrier identifiers. It does not restate the 'give at least one of dot, mc or broker_mc' constraint as clearly as the schema does, but the section-to-param linkage is real added value.

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 action and a well-defined composite resource: authority + SMS BASICs + broker authority + optional OFAC name screen, with the 'vet pack' framing. It is distinguishable from the granular siblings (check_carrier_authority, check_carrier_basics, check_broker_authority, screen_sanctions_name) by listing all four components in one call, though it never explicitly says 'this is the bundled alternative to those single-check 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?

'Pre-tender check' gives a clear situational context, and the description scopes which params trigger which sections ('broker authority for broker_mc', 'optional OFAC name screen'). However, it never names the cheaper single-purpose siblings as the alternative when only one check is needed, so the agent must infer when to pick this pack over them.

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