Skip to main content
Glama
@blackwood-state/mcp

@blackwood-state/mcp

@blackwood-state/mcp

Blackwood State tools for AI agents over MCP. The package gives 33 pay-per-call tools, paid in USDC on Base over x402:

  • onchain data: token prices, wallet balances and portfolio value, ENS, gas fees, new token pools;

  • ECB exchange rates;

  • text utilities: summarize, translate, sentiment;

  • and more.

The server holds no wallet by default: when a call needs payment, it hands the agent the command that pays it from the wallet the agent already has (AgentCash or the Coinbase Agentic Wallet), capped at the price of that call.

claude mcp add blackwood -- npx -y @blackwood-state/mcp

Any MCP client over stdio:

{ "mcpServers": { "blackwood": { "command": "npx", "args": ["-y", "@blackwood-state/mcp"] } } }

How payment works

  1. Free demo credit. On first use, the server asks for US$0.05 of credit (one per IP per day) and keeps the key in ~/.blackwood/state.json. Set BLACKWOOD_NO_TRIAL=1 to skip it.

  2. Then the wallet you already have. Without credit, a paid tool returns its live price and two ready commands, and nothing is charged:

    • AgentCash: npx -y agentcash@0.17.1 fetch '<url>' -m POST -b '<json>' --max-amount <usd>

    • Coinbase Agentic Wallet, after npx awal auth login: npx -y awal@2.12.2 x402 pay '<url>' -X POST -d '<json>' --max-amount <atomic> The agent should ask the user before paying, unless the user already approved a budget.

  3. Other ways:

    • Prepaid credit: BLACKWOOD_CREDITS_KEY, a key bought at /v1/credits/5.

    • Advanced mode: BLACKWOOD_PRIVATE_KEY, a Base wallet that this server signs x402 payments with, only for Base USDC and only within the caps. Use a dedicated wallet that holds only what you plan to spend.

  4. Never charged for failures. A call that fails or rejects the input costs nothing.

Variable

Default

BLACKWOOD_CREDITS_KEY

none

prepaid credit key (bwk_...)

BLACKWOOD_PRIVATE_KEY

none

advanced mode: Base wallet that pays per call over x402

BLACKWOOD_MAX_USD_PER_CALL

0.05

cap per call in advanced mode

BLACKWOOD_MAX_USD_PER_DAY

1

cap per UTC day in advanced mode

BLACKWOOD_NO_TRIAL

unset

1 skips the free demo credit

BLACKWOOD_HOME

~/.blackwood

state directory

blackwood_account (free) shows the credit left, the paying wallet (advanced mode), today's spend and the caps.

The same routes are plain HTTP endpoints. Each one answers 402 with its price; see the OpenAPI at https://x402-gateway.blackwoodstate8.workers.dev/openapi.json. A skill for Agent Skills clients ships in skills/blackwood-state/SKILL.md.

Source: https://github.com/Blackwood-State/mcp. MIT license.

Available Tools

34 tools
blackwood_accountBlackwood accountA
Read-only

Free. Shows the credit balance, the wallet that pays over x402 (if any), today's spend and the caps.

NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior4/5

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

readOnlyHint=true already covers the safety profile, and the description adds genuinely new behavior: the call is free of charge and the paying wallet is only shown 'if any', which warns the agent the field may be absent. It does not describe the shape of the caps response, but that is a minor gap given the read-only annotation.

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

Conciseness5/5

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

A single sentence, front-loaded with the cost factor 'Free.' then the returned fields. No filler and nothing an agent must scroll past.

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

Completeness4/5

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

With no output schema, the description carries the return-value burden and largely discharges it by listing the four values returned. A brief note on response format or whether the wallet field is null vs omitted would make it complete.

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

Parameters4/5

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

Zero parameters, so there is nothing for the description to disambiguate; baseline applies. The description correctly signals the tool is argument-free by describing only outputs.

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

Purpose4/5

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

Specific verb 'shows' with an enumerated resource set: credit balance, paying wallet, today's spend, and caps. This clearly separates it from data siblings like blackwood_wallet_balances or blackwood_wallet_portfolio (on-chain balance data) since it describes account-level credits and spend limits, though it never states that distinction explicitly.

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

Usage Guidelines3/5

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

'Free' implies it can be called without cost, and the content implies it is an account-status check, but there is no explicit when-to-use guidance such as 'call before paid tools to verify remaining credits' nor any named alternative among the 30+ siblings.

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

blackwood_airport_delaysAirport delaysA

Use when you need airport delays, FAA ground stops or the airport status of a US airport right now, such as departure delays or closures. Do not use for the status of a flight number, airports outside the US or historical delays. Returns JSON with current US airport delays from the FAA: ground stops, ground delay programs with average and maximum delay, arrival and departure delays and closures, for all airports or one for 0.007 USDC per call. Typical response time 1500 ms (p95). Category: Data. Price: US$0.007 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
airportNoUS airport code to filter, e.g. SFO or KSFO (all airports with delays when omitted)

TDQS

A4.6/5.0
Behavior5/5

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

Annotations are sparse and partly surprising (readOnlyHint=false for a data fetch), and the description reconciles this by disclosing the per-call charge, the wallet payment path when the demo credit runs out, and the returned command on unpaid calls. It also gives a p95 latency figure and enumerates the response payload fields, none of which the annotations carry.

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

Conciseness4/5

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

Usage and exclusions are front-loaded, then payload, price, latency, and payment mechanics follow in a logical order. Slightly redundant on price ('0.007 USDC per call' then 'Price: US$0.007 per call'), which keeps it off a 5.

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

Completeness5/5

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

There is no output schema, and the description compensates by enumerating what the JSON contains (ground stops, delay programs with average and maximum delay, arrival/departure delays, closures). With one fully documented optional parameter and the payment/latency behavior covered, an agent has everything needed to call it correctly.

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

Parameters3/5

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

Schema coverage is 100% and the single parameter already carries its own description and pattern, so the schema does the heavy lifting. The description only restates the omit-for-all-airports behavior ('for all airports or one'), adding no syntax or format detail beyond the schema; baseline 3 applies.

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

Purpose5/5

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

States a specific resource and scope: current US airport delays, FAA ground stops, ground delay programs, arrival/departure delays and closures. It explicitly excludes flight-number status, non-US airports and historical delays, so an agent can distinguish it from every sibling in the list without opening the schema.

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

Usage Guidelines5/5

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

Opens with an explicit 'Use when...' condition and follows with a 'Do not use for...' list naming the three most likely misroutes (flight number status, non-US airports, historical data). The alternative-condition framing is exactly what the dimension asks for.

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

blackwood_altcoin_discoveryAltcoin discovery on BaseA

Use when you need altcoin discovery, new token listings or fresh Base tokens with real liquidity to research. Do not use for established coins, other chains or DEXs, price history, trading signals or token safety audits. Returns JSON with new tokens on Base that just got liquidity: Uniswap v3 pools created in the last hours against WETH or USDC, read on-chain from pool creation events, with price, depth and age for 0.005 USDC per call. Typical response time 3000 ms (p95). Category: Trading. Price: US$0.005 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
hoursNoLook back this many hours for new pools, 1 to 72 (24 when omitted), e.g. 24
limitNoTokens to return, 1 to 25 (10 when omitted), e.g. 5
quoteNoQuote side of the pool (any when omitted), e.g. "WETH"
minDepthUsdNoMinimum USD on the WETH or USDC side of the pool (5000 when omitted), e.g. 10000

TDQS

A4.5/5.0
Behavior5/5

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

Annotations are present, so the bar is lower, but the description adds substantial context they cannot carry: the on-chain provenance, p95 latency of 3000 ms, per-call cost of US$0.005, and the full payment path (free demo credit, then an x402 command paid from the caller's own wallet via AgentCash or Coinbase Agentic Wallet). The payment flow also implicitly explains why readOnlyHint is false despite the operation being a read — an important nuance an agent would otherwise misread.

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

Conciseness4/5

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

Usage guidance and exclusions are front-loaded, and the return-shape sentence follows before the commercial boilerplate. There is mild redundancy — '0.005 USDC per call' is restated as 'Price: US$0.005 per call', and 'Category: Trading' adds little — but no sentence is wasted enough to obscure selection.

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

Completeness4/5

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

With no output schema, the description takes on the burden and mostly meets it: the response is described as new Base tokens with price, depth and age, plus latency and cost. Exact JSON field names remain unspecified, so an agent knows the shape but not the keys — the main residual gap for a zero-required-param, fully-self-described tool.

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

Parameters3/5

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

Schema description coverage is 100% with per-field ranges, defaults and examples, so the schema already does the heavy lifting and baseline 3 applies. The description only lightly reinforces semantics by noting pools are quoted 'against WETH or USDC' and results include 'depth' and 'age', which hints at the quote and minDepthUsd filters without adding format or tuning guidance.

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

Purpose5/5

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

States a specific verb and resource — altcoin discovery of freshly-created Uniswap v3 pools on Base quoted in WETH or USDC — plus the exact data source (on-chain pool creation events). This clearly separates it from siblings like blackwood_token_price (price lookups) and blackwood_crypto_news (news), which an agent could otherwise confuse with 'new token' research.

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

Usage Guidelines5/5

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

Explicitly names when to use it (new listings, fresh Base tokens with real liquidity) and enumerates five exclusions: established coins, other chains or DEXs, price history, trading signals, and safety audits. Each exclusion maps to a plausible sibling or misuse case, leaving nothing to inference.

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

blackwood_audio_transcribeSpeech to textA

Use when you need speech to text transcription or translation of an audio file at a public URL. Do not use for audio over 10 MB or speaker labels. Returns JSON with a Whisper transcription of an audio file: text, timed segments and language, or an English translation for 0.005 USDC per megabyte, up to 0.05 USDC per call (clients without upto pay the cap). Result in the same call (about 20000 ms); a status tool polls for free if it takes longer. Category: Media. Price: US$0.05 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
urlYesPublic http(s) URL of the audio file, e.g. https://example.com/talk.mp3 (mp3, wav, ogg, m4a, webm; up to 10 MB)
taskNotranscribe keeps the spoken language; translate returns English (transcribe when omitted)
languageNoISO 639-1 code of the spoken language, e.g. en or pt (detected when omitted)

TDQS

A4.4/5.0
Behavior5/5

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

Beyond annotations, the description discloses return format (text, timed segments, language), latency (~20,000 ms), an alternative polling path, pricing (0.005 USDC/MB, capped at 0.05 USDC), the free demo credit, and the wallet-payment fallback. These are material behavioral details an agent needs before invoking a paid, open-world tool.

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

Conciseness4/5

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

The description is front-loaded with purpose and exclusions, then moves to return format, latency, and payment details. It is slightly dense with pricing and wallet-fallback information, but each sentence carries operational value for a paid API tool.

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

Completeness5/5

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

There is no output schema, but the description explains the return shape (Whisper transcript with text, timed segments, language, or English translation) and the fallback polling behavior. Combined with full schema coverage, an agent has everything needed to call the tool correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the schema already explains url, task, and language thoroughly. The description reinforces the transcribe/translate distinction and size limit but adds no syntax, format, or default details beyond what the schema provides; baseline 3 is appropriate.

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

Purpose5/5

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

The description opens with a specific verb and resource: speech-to-text transcription or translation of an audio file at a public URL. It clearly distinguishes the tool from siblings like blackwood_speech_synthesize and blackwood_text_translate by naming the input (audio URL) and output (Whisper transcript). An agent can identify the tool without opening the schema.

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

Usage Guidelines4/5

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

It gives explicit when-to-use guidance and clear exclusions: 'Do not use for audio over 10 MB or speaker labels.' It does not name a sibling alternative for those excluded cases, but the conditions for use and non-use are directly stated and actionable.

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

blackwood_company_dossierCompany research dossierA

Use when you need company research, due diligence or a quick analysis of a business from its website domain and optional ticker. Do not use for private financials, credit scores, people search or businesses without a website. Returns JSON with a company research dossier in one call: domain registration and DNS, email and website security, latest news and, with a ticker, SEC financials, priced below the separate calls for 0.03 USDC per call. Typical response time 8000 ms (p95). Category: Data. Price: US$0.03 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
nameNoCompany name for the news search (taken from the domain when omitted), e.g. Stripe
domainYesCompany website domain, e.g. stripe.com
tickerNoStock ticker for SEC financials, US filers only (no financials when omitted), e.g. AAPL

TDQS

A4.1/5.0
Behavior5/5

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

Annotations only declare hints; the description adds the economically important behavior: 0.03 USDC per call, 8000 ms p95 latency, a free demo credit, and that after the credit the tool returns a wallet payment command rather than a result. That disclosure explains why readOnlyHint=false despite it being a research read, and prevents an agent from treating a paywall response as a failure.

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

Conciseness4/5

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

Front-loads the trigger and exclusions, then the return payload, then cost and latency — a sensible ordering. It is somewhat long, and 'Category: Data. Price: US$0.03 per call.' partly duplicates the pricing already stated in the preceding sentence.

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

Completeness4/5

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

With no output schema, the description enumerates the returned sections (domain registration and DNS, email and website security, news, SEC financials with ticker), plus latency and payment flow, which is enough to decide and invoke. Minor gaps remain around failure modes for an invalid or unreachable domain.

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

Parameters3/5

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

Schema description coverage is 100%, with all three parameters documented including the ticker pattern and US-filer constraint, so the baseline is 3. The description restates the domain/ticker contract ('with a ticker, SEC financials') but adds no semantics the schema lacks, such as what happens to the name parameter when omitted.

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

Purpose4/5

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

States a concrete composite purpose: build a company research dossier from a website domain and optional ticker, aggregating DNS, security, news and SEC financials. This is clearly distinguishable from narrow siblings like blackwood_domain_intel or blackwood_sec_facts, though no sibling is named explicitly.

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

Usage Guidelines4/5

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

Opens with an explicit 'Use when you need company research, due diligence or a quick analysis' trigger and a 'Do not use for private financials, credit scores, people search or businesses without a website' exclusion list, which is stronger than most. The alternative it implies ('priced below the separate calls') is indirect rather than naming the specific single-purpose tools to use instead.

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

blackwood_crypto_newsCrypto newsA

Use when you need crypto news or crypto market news headlines about a token or the market from recent articles. Do not use for prices, full article text, social media posts or news older than 72 hours. Returns JSON with the latest crypto news headlines from the last 72 hours (title, link, source, time, tone, people and organizations) about bitcoin, ethereum and blockchain news, from the GDELT news graph for 0.005 USDC per call. Typical response time 1500 ms (p95). Category: Search. Price: US$0.005 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
hoursNoHow far back to search, in hours (1-72, default 24)
limitNoMost articles to return (1-50, default 20), newest first
tokenNoNarrow to one coin, chain or company, e.g. solana, xrp or coinbase (any crypto news when omitted)

TDQS

A4.3/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses price (0.005 USDC/call), the payment path (free demo credit, then an x402 payment command from AgentCash/Coinbase Agentic Wallet), p95 latency of 1500 ms, and the exact return fields (title, link, source, time, tone, people, organizations). The readOnlyHint=false is explained by the per-call charge rather than unspecified state mutation.

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

Conciseness3/5

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

Usage constraints and the 72-hour window are correctly front-loaded, but the price is stated twice ('0.005 USDC per call' in prose, then 'Price: US$0.005 per call' as a field) and the payment/demo-credit paragraph plus 'Category: Search' add boilerplate weight. Trimming the duplicated pricing line would make it materially tighter.

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

Completeness5/5

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 contract and does so by listing the JSON fields an agent receives. Combined with freshness limits, cost, latency and payment behavior, an agent has everything needed to decide and call correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so hours, limit and token are already fully documented with ranges and defaults; the description adds no per-parameter syntax or behavior beyond the schema. The mention of 'about bitcoin, ethereum and blockchain news' hints at the token parameter's domain but does not add operational detail.

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

Purpose5/5

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

States a specific verb+resource — crypto news headlines about a token or the market from recent articles — and immediately bounds the scope (last 72 hours, headline-level, not prices or full text). An agent can distinguish it from blackwood_news_search, blackwood_token_price and blackwood_webpage_markdown 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.

Usage Guidelines4/5

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

Gives an explicit when-to-use condition plus four explicit exclusions (prices, full article text, social posts, news older than 72 hours), which is stronger than most definitions. The only gap is that it never names the sibling tool to use instead for a rejected case (e.g. token_price, news_search), leaving that routing to inference.

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

blackwood_domain_intelDomain intelligenceA

Use when you need a domain lookup, whois, dns records or certificate transparency data for osint, security or due diligence. Do not use for historical whois, registrant personal data (redacted by registries) or port and vulnerability scans. Returns JSON with domain intelligence: WHOIS/RDAP registration, DNS records (A, AAAA, MX, NS, TXT, CAA), SPF and DMARC, and TLS certificates from certificate transparency logs for 0.02 USDC per call. Typical response time 4000 ms (p95). Category: Data. Price: US$0.02 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
domainYesDomain name in ASCII (punycode for internationalized names), e.g. example.com
certificatesNoInclude issued TLS certificates from Certificate Transparency (crt.sh); true when omitted

TDQS

A4.4/5.0
Behavior4/5

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

Goes well beyond the annotations by disclosing the return payload contents, a per-call price, p95 latency, and the free-credit-then-wallet-payment flow — important because readOnlyHint=false and non-idempotency are otherwise unexplained. The only gap is that it never explicitly says why the call is not read-only (the wallet payment side effect), leaving the annotation unaccounted for.

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

Conciseness4/5

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

Usage constraints and payload are front-loaded and the sentences are compact. However, the price is stated twice ("0.02 USDC per call" and "Price: US$0.02 per call") and "Category: Data" adds little, which is mild redundancy.

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

Completeness5/5

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

With no output schema, the description fully enumerates what comes back (WHOIS/RDAP, record types, SPF/DMARC, CT certificates) and covers the commercial/billing behaviour. Nothing needed to decide to call it or to interpret the response is missing.

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

Parameters3/5

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

Schema coverage is 100% and both parameters carry descriptions, including the default for certificates=true, so the schema does the heavy lifting. The description adds only the general payload list, not per-parameter meaning, so the baseline of 3 applies.

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

Purpose5/5

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

The first sentence names specific verbs and resources (domain lookup, whois, dns records, certificate transparency) and the return payload is enumerated, so an agent knows exactly what the call produces. It is clearly distinguishable from the neighbouring ens_lookup and headers_audit style tools by scope.

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

Usage Guidelines5/5

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

Explicit when-to-use triggers (osint, security, due diligence) plus explicit exclusions: historical whois, redacted registrant data, and port/vulnerability scans. That is exactly the when/when-not guidance an agent needs to avoid mis-selection.

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

blackwood_email_batchEmail list checkA

Use when you need bulk email validation, email list verification or to verify email lists before a send or import. Do not use for one address (email-check is cheaper), proving a mailbox exists (no SMTP probe) or sending email. Returns JSON checking up to 20 email addresses in one call: syntax, MX records, disposable, free and role flags, SPF, DMARC and a verdict each, plus counts by verdict for 0.02 USDC per call. Typical response time 2500 ms (p95). Category: Data. Price: US$0.02 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
emailsYesEmail addresses to check, 1 to 20, e.g. ["jane@example.com", "info@ietf.org"]

TDQS

A4.6/5.0
Behavior4/5

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

Adds substantial context beyond the annotations: per-call price (0.02 USDC), a free demo credit, the fallback behavior once credit runs out (returns the paying command for AgentCash/Coinbase Agentic Wallet), batch cap of 20, and p95 latency. The one gap is that readOnlyHint=false is not explained — an agent might not realize the call debits a wallet balance, though the pricing text implies it.

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

Conciseness4/5

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

Front-loaded with the use/do-not-use decision, then returns, then pricing — a sensible order for an agent scanning before invocation. The payment mechanics sentence is long but is operationally required for a paid x402-style tool, so it earns its place rather than being filler.

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

Completeness5/5

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

No output schema exists, yet the description enumerates the returned checks and the aggregate counts by verdict, plus latency and cost. For a single-parameter batch validator, nothing an agent needs in order to call it or interpret the result is missing.

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

Parameters4/5

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

Schema coverage is 100% and the single 'emails' parameter is fully documented in the schema, so the baseline is a 3. The description still adds the batch ceiling of 20 and confirms what is computed per address (syntax, MX, disposable/free/role flags, SPF, DMARC, verdict), which orients the agent on input grouping rather than restating option names.

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

Purpose5/5

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

States a specific verb and resource ('bulk email validation, email list verification') and scopes it to lists rather than single addresses. It explicitly names the cheaper sibling blackwood_email_check as the alternative, so an agent can distinguish the two 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.

Usage Guidelines5/5

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

Gives an explicit when-to-use clause ('before a send or import'), three explicit when-not clauses (single address, proving mailbox existence, sending email), and routes the single-address case to a named alternative. There is nothing left to infer about tool selection.

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

blackwood_email_checkEmail validationA

Use when you need email validation, to verify email addresses or validate email syntax and MX records before sending or signup. Do not use for confirming that the mailbox itself exists (no SMTP probe is done) or sending email. Returns JSON with email verification of one address: syntax, domain MX records, disposable, free and role-account flags, SPF and DMARC, and a verdict on whether the domain can receive mail for 0.005 USDC per call. Typical response time 800 ms (p95). Category: Data. Price: US$0.005 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
emailYesEmail address to check, e.g. jane@example.com

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses pricing (US$0.005/call), p95 latency (~800 ms), the free demo credit and the payment handoff flow, and the key limitation that no SMTP probe is performed. These are exactly the operational traits an agent needs and none are inferable from the schema or hints.

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

Conciseness4/5

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

Front-loads the use/when-not guidance, then results, then commercial terms, and every sentence carries information. The payment paragraph is dense but necessary for a paid-per-call tool; only marginal tightening is possible.

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

Completeness5/5

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

With no output schema, the description enumerates the returned fields (syntax, MX, disposable/free/role flags, SPF, DMARC, verdict) and covers cost and payment behavior, so an agent knows both what it gets and what it must do to get it. Nothing essential for correct invocation is missing.

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

Parameters3/5

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 format and bounds (3-254 chars). The description only reinforces scope with 'one address', adding little beyond the schema, which is the baseline case for full coverage.

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

Purpose4/5

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

States a specific verb and resource ('email validation', 'verify email addresses or validate email syntax and MX records') and enumerates the verification signals returned. It implicitly distinguishes itself from blackwood_email_batch via 'verification of one address', but never names that sibling, so an agent must infer the single-vs-batch split.

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

Usage Guidelines4/5

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

Explicit when-to-use ('before sending or signup') and when-not-to-use ('Do not use for confirming that the mailbox itself exists... or sending email'), which is unusually clear. It omits the obvious alternative, blackwood_email_batch, for multi-address validation, leaving that routing decision to the agent.

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

blackwood_ens_lookupENS name lookupA

Use when you need to resolve an ENS name to an address, reverse-resolve an address to its ENS name, or read an ENS avatar and profile records. Do not use for registering or renewing names, or non-ENS naming such as Solana SNS. Returns JSON with an ENS lookup on Ethereum in one call: the address of a name, the verified primary name of an address (reverse), the avatar and text records such as url, twitter and github for 0.005 USDC per call. Typical response time 2000 ms (p95). Category: Data. Price: US$0.005 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
nameNoENS name to resolve, e.g. vitalik.eth (send name or address, not both)
textsNoText record keys to read (avatar, url, description, com.twitter, com.github and email when omitted), e.g. ["url", "com.github"]
addressNoEthereum address to reverse-resolve, e.g. 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 (send name or address, not both)

TDQS

A4/5.0
Behavior4/5

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

Adds substantial context beyond annotations: per-call price of 0.005 USDC, a free demo credit, the fallback flow returning a payment command for AgentCash/Coinbase wallets, and p95 latency of 2000 ms. This is genuinely useful for planning calls. Minor tension: annotations declare readOnlyHint=false and idempotentHint=false, but the description frames the tool purely as reads; the paid-call side effect plausibly explains it, though the description never reconciles the two.

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

Conciseness3/5

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

Front-loaded with the usage rule, which is good, but the middle is redundant: the second sentence re-enumerates the same three operations already listed in the first, and the price appears twice ("0.005 USDC per call" and "Price: US$0.005 per call"). Trimming would lose nothing.

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

Completeness4/5

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 describes the return shape (address of a name, verified primary name, avatar and text records) as JSON, plus latency and payment mechanics. Only gap is not clarifying what happens when neither name nor address is supplied, given zero required parameters.

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

Parameters3/5

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

Schema coverage is 100%, including the mutual-exclusivity note ("send name or address, not both") and default text keys, so the schema already carries the parameter burden. The description restates the three capabilities but adds no format, precedence, or default behavior beyond the schema.

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

Purpose5/5

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

States specific verbs and resources: resolve ENS name to address, reverse-resolve address to name, read avatar and text records on Ethereum. It also explicitly names what it is not (name registration/renewal, Solana SNS), so an agent can separate it from adjacent naming tools.

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

Usage Guidelines4/5

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

Opens with an explicit "Use when..." trigger list and adds a "Do not use for..." exclusion, which is stronger than most definitions. It does not point to any sibling tool for the excluded cases (e.g. blackwood_domain_intel), so routing within the toolset is left slightly incomplete.

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

blackwood_fx_historyHistorical exchange ratesA

Use when you need historical exchange rates, a historical FX rate series, forex history or a currency trend. Do not use for rates older than 90 days, live quotes or crypto (one ECB rate per business day). Returns JSON with historical exchange rates: 90 days of daily ECB euro reference rates (free at ecb.europa.eu) for up to 10 currencies, rebased to any base as cross rates, with min, max and percent change for 0.005 USDC per call. Typical response time 1500 ms (p95). Category: Data. Price: US$0.005 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
baseNoBase currency, ISO 4217 (EUR when omitted), e.g. USD
daysNoCalendar days back from endDate, 1 to 90 (90 when omitted; ignored with startDate), e.g. 30
endDateNoLast day, YYYY-MM-DD (latest ECB day when omitted), e.g. 2026-09-30
symbolsYesCurrencies to return, ISO 4217, up to 10, e.g. ["USD", "BRL"]
startDateNoFirst day, YYYY-MM-DD, within the last 90 days, e.g. 2026-09-01

TDQS

A4.6/5.0
Behavior5/5

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

Goes well past the annotations: discloses data source (ECB, free at ecb.europa.eu), freshness granularity (one rate per business day), hard caps (10 currencies, 90 days), cost (US$0.005/call), latency (p95 1500 ms), and the payment path (free demo credit, then a returned command that pays from AgentCash/Coinbase Agentic Wallet). The readOnlyHint=false sits consistently with the described paid-call side effect rather than contradicting it.

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

Conciseness4/5

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

Front-loaded with the selection rule and exclusions before the return spec, so the reader hits the decision-relevant content first. Minor waste: pricing appears twice ('0.005 USDC per call' and the 'Category/Price' trailer), and the payment-flow sentence is longer than needed.

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

Completeness5/5

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 return-shape burden and does it: JSON with daily rates plus min, max, and percent change. Combined with source, coverage limits, latency, and cost, an agent has everything needed to decide and invoke correctly.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description raises it by explaining that results are rebased to any base as cross rates and capped at 10 symbols over a 90-day window, which gives 'base' and 'symbols' meaning beyond their pattern/maxItems constraints. It does not explain the startDate/endDate/days interaction, which the schema handles only partially.

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

Purpose5/5

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

States a specific verb and resource ('historical exchange rates', 'daily ECB euro reference rates') and backs it with concrete scope: 90 days, up to 10 currencies, rebased cross rates. It also fences itself off from live quotes and crypto, which is exactly what the sibling blackwood_fx_rates covers, so an agent can discriminate without opening schemas.

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

Usage Guidelines4/5

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

Explicit 'Use when' triggers (FX history, currency trend) and explicit exclusions (rates older than 90 days, live quotes, crypto) with the one-ECB-rate-per-business-day constraint spelled out. It routes by capability rather than naming the sibling tool ('live quotes' rather than blackwood_fx_rates), which is clear but one notch short of fully explicit alternatives.

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

blackwood_fx_ratesCurrency exchange ratesA

Use when you need currency exchange rates, fx rates or forex conversion of an amount between two currencies like EUR and GBP. Do not use for live trading quotes, intraday or crypto rates (ECB rates update once per business day). Returns JSON with currency exchange rates: official ECB euro reference FX rates (free at ecb.europa.eu) for about 30 currencies, rebased to any base as cross rates, with optional conversion for 0.005 USDC per call. Typical response time 1500 ms (p95). Category: Data. Price: US$0.005 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
baseNoBase currency, ISO 4217 (EUR when omitted), e.g. USD
amountNoAmount in the base currency to convert, e.g. 100
symbolsNoCurrencies to return, e.g. ["BRL", "JPY"] (all ECB currencies when omitted)

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already flag openWorldHint=true and readOnlyHint=false, and the description goes well beyond them with pricing (US$0.005/call), payment mechanics (demo credit then wallet-settled command), latency (1500 ms p95), and the once-per-business-day refresh cadence — genuinely useful for a paid x402 tool. It does not, however, explain why readOnlyHint is false despite this being a pure lookup, nor what happens on a failed/settled-but-empty call, which is the one behavioral question an agent would still have.

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

Conciseness4/5

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

Front-loaded with the 'Use when' clause before the pricing and plumbing details, which is the right order. It carries a little commercial boilerplate ('Category: Data.', the demo-credit sentence) that a caller must read through, but for a metered x402 tool that information is load-bearing rather than padding.

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

Completeness5/5

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 carries the return-shape burden and does: JSON, ~30 ECB currencies, cross-rate rebasing, optional converted amount. Combined with the freshness caveat and payment note, 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.

Parameters3/5

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

Schema coverage is 100% and already documents defaults (EUR base, all ECB currencies for symbols) and ISO 4217 patterns, so the schema does the heavy lifting. The description adds the cross-rate/rebasing mental model ('rebased to any base as cross rates') and the notion of optional amount conversion, but not enough to shift the baseline upward.

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

Purpose5/5

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

States a specific verb and resource ('currency exchange rates, fx rates or forex conversion of an amount between two currencies') with a concrete example pair (EUR/GBP), and pins the data source (official ECB euro reference rates, ~30 currencies) so an agent can distinguish it from token_price or fx_history 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.

Usage Guidelines5/5

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

Gives an explicit 'Use when...' trigger and an explicit 'Do not use for...' exclusion set (live trading quotes, intraday, crypto), which effectively routes the agent to crypto/token siblings and away from this tool. The only soft spot is that no sibling is named directly, but the categorical exclusions are unambiguous.

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

blackwood_gas_feesGas price and feesA

Use when you need the current gas price, an ethereum gas fee estimate before a transaction, or to compare gas fees across chains. Do not use for gas units of a given transaction, gas history or chains beyond Ethereum, Base and Solana. Returns JSON with the gas price and gas fees on Ethereum and Base (base fee, slow, standard and fast EIP-1559 fees in gwei, transfer cost) plus Solana priority fees for 0.003 USDC per call. Typical response time 1500 ms (p95). Category: Data. Price: US$0.003 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
chainsNoChains to read (ethereum, base and solana when omitted), e.g. ["base", "ethereum"]

TDQS

A4.6/5.0
Behavior5/5

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

Annotations only declare the generic read/write flags (readOnlyHint=false, openWorldHint=true, destructiveHint=false, idempotentHint=false); the description adds the substantive behavior: the paid nature (US$0.003/call, free demo credit, then a wallet-payment command is returned), p95 latency of ~1500 ms, and exactly which fields come back. That extra context — especially the payment step, which plausibly explains the non-read-only annotation — is materially beyond what structured fields convey.

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

Conciseness4/5

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

Front-loaded with the when-to-use clause before mechanics, which is the right ordering for selection. Slight waste: pricing appears twice ('0.003 USDC per call' and 'Price: US$0.003 per call') and 'Category: Data.' is low-value metadata, but nothing is bloated enough to impede scanning.

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

Completeness5/5

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

With no output schema, the description takes on the return-value burden and does it: it enumerates base fee, slow/standard/fast EIP-1559 fees in gwei, transfer cost, and Solana priority fees. Combined with cost, latency, and the payment fallback path, an agent has everything needed to call it and interpret the result.

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

Parameters3/5

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

Schema coverage is 100% and the single `chains` property already documents the enum, the max 3/min 1 bounds, the default-on-omission behavior, and gives an example. The description only echoes that scope ('Ethereum and Base and Solana', 'chains beyond... not supported') without adding syntax or default detail, so baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource — reading the current gas price and EIP-1559 fee estimates — and names the exact scope (Ethereum, Base, Solana). It also carves out what it is not (gas units for a specific transaction, gas history, other chains), so an agent can separate it from siblings like blackwood_token_price or blackwood_wallet_balances 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.

Usage Guidelines5/5

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

Explicit 'Use when you need...' triggers (pre-transaction fee estimate, cross-chain fee comparison) paired with an explicit 'Do not use for...' exclusion list. This is the when/when-not pattern at its clearest, leaving no inference needed about selection.

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

blackwood_headers_auditSecurity headersA

Use when you need an http security headers audit of a website or URL, with a grade and what to fix. Do not use for vulnerability scans, TLS cipher analysis or pages behind a login. Returns JSON auditing the HTTP security headers of a public URL (HSTS, CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, cookies) with a grade and fixes for 0.007 USDC per call. Typical response time 2500 ms (p95). Category: Infrastructure. Price: US$0.007 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
urlYesPublic http(s) URL to audit, e.g. https://example.com

TDQS

A4.8/5.0
Behavior5/5

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

Far beyond the annotations: discloses cost per call, latency (p95 2500 ms), free demo credit, and the x402-style payment fallback ('returns the command that pays the call from your own wallet'). Annotations only cover safety/idempotency hints, so this payment and quota context is genuinely additive.

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

Conciseness4/5

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

Front-loaded with use-when and exclusions, and the return contents are enumerated usefully. Deduction for price duplication ('0.007 USDC per call' then 'Price: US$0.007 per call'), which is redundant.

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

Completeness5/5

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 listing the audited headers and the grade/fix payload. Payment and latency requirements, which an agent must know before calling, are stated.

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

Parameters4/5

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

Schema coverage is 100% and already documents the single url parameter, so the baseline is 3. The description adds meaning by scoping it to a 'public URL' and excluding login-protected pages, which sharpens what a valid value is.

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

Purpose5/5

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

States a specific verb+resource ('http security headers audit of a website or URL') and the deliverable ('grade and what to fix'). It also names what it is not (vulnerability scan, TLS cipher analysis), which separates it from any adjacent sibling in a large toolset.

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

Usage Guidelines5/5

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

Explicit 'Use when' clause plus three concrete exclusions ('vulnerability scans, TLS cipher analysis, pages behind a login'). The agent has both the selection condition and the disqualifiers.

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

blackwood_image_generateImage generationA

Use when you need image generation, an AI image generator or text to image from a prompt for illustrations, mockups or social posts. Do not use for image edits, specific sizes, photos of real people or more than one image per call. Returns JSON with an AI-generated image from a text prompt: a 1024x1024 JPEG made by FLUX.1 schnell on Workers AI, as base64 for 0.03 USDC per call. Result in the same call (about 10000 ms); a status tool polls for free if it takes longer. Category: Media. Price: US$0.03 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
stepsNoDiffusion steps (1-8, 4 when omitted); more steps, more detail
promptYesWhat the image should show, in English, e.g. a lighthouse on a cliff at sunset, watercolor

TDQS

A4.6/5.0
Behavior5/5

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

Annotations cover the safety profile (readOnlyHint=false, destructiveHint=false, openWorldHint=true), and the description adds substantial context beyond them: exact model (FLUX.1 schnell on Workers AI), output format (1024x1024 JPEG base64), price (0.03 USDC/call), latency (~10000 ms), the free polling alternative, and the wallet payment flow after the demo credit. This is unusually complete.

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

Conciseness4/5

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

The most important information (use case and exclusions) is front-loaded, and every sentence carries useful content. It is dense and packs pricing, model, latency and payment flow into long clauses, which sacrifices some readability but avoids filler.

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

Completeness5/5

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

There is no output schema, but the description describes the return value precisely (JSON with a base64 1024x1024 JPEG) so the agent knows what comes back. Pricing, timing, and the fallback status tool are all covered, leaving no gap for correct invocation.

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

Parameters3/5

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

Schema coverage is 100%, so both parameters (prompt, steps) are fully documented in the schema with defaults and ranges. The description restates that the input is a text prompt but adds no 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.

Purpose5/5

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

The description opens with a specific verb and resource ('image generation... text to image from a prompt') and names intended uses (illustrations, mockups, social posts). It also explicitly carves out what it is not (image edits, real-person photos), making it distinguishable from any sibling.

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

Usage Guidelines5/5

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

It states clear when-to-use conditions, four explicit exclusions ('Do not use for image edits, specific sizes, photos of real people or more than one image per call'), and points to the status tool as the alternative for long-running polls. Alternatives and boundaries are fully spelled out.

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

blackwood_llm_chatLLM chat completionA

Use when you need an llm chat completion for summaries, extraction or classification from a cheap open model. Do not use for frontier models, tool calling or streaming. Returns JSON with a chat completion from IBM Granite 4.0 Micro on Workers AI, with token usage for 0.002 USDC per thousand tokens, up to 0.03 USDC per call (clients without upto pay the cap). Result in the same call (about 8000 ms); a status tool polls for free if it takes longer. Category: Inference. Price: US$0.03 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
messagesYesConversation so far, oldest first, e.g. [{"role": "user", "content": "Summarize: ..."}]
maxTokensNoMaximum tokens to generate (1-4096, 512 when omitted); billed as requested
temperatureNoSampling temperature (0-2), e.g. 0.2 for near-deterministic output

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses per-token pricing with a per-call cap, the ~8000 ms synchronous window, the free status-polling escape hatch, the demo-credit exhaustion path, and the payment command returned when credit runs out. Also states the return shape (JSON chat completion plus token usage), which is critical since no output schema exists.

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

Conciseness4/5

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

Front-loaded with the use case and the exclusions before commercial detail, which is the right order. It loses a point for restating the price twice ('up to 0.03 USDC per call' and 'Price: US$0.03 per call'), a mildly redundant tail.

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

Completeness5/5

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

For a paid, synchronous, non-streaming inference call with no output schema, the description supplies everything an agent needs: cost and cap, latency expectation, polling fallback, payment prerequisite, and the shape of the returned JSON.

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

Parameters3/5

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

Schema description coverage is 100%, so messages, maxTokens and temperature are already fully documented with ranges, defaults and billing notes in the schema. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

Purpose4/5

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

States a specific verb+resource (LLM chat completion) with the exact underlying model (IBM Granite 4.0 Micro on Workers AI) and intended tasks (summaries, extraction, classification). It distinguishes itself from frontier-model offerings, though it does not name the overlapping siblings such as blackwood_text_summarize or blackwood_text_sentiment.

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

Usage Guidelines4/5

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

Explicit 'Use when...' clause plus explicit exclusions ('Do not use for frontier models, tool calling or streaming'). It lacks a named alternative tool to route to for the summarization/classification cases it advertises, so it falls short of full sibling routing.

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

blackwood_news_briefingNews research briefingA

Use when you need a news briefing, a research summary of recent coverage or an analysis of what the press says about a topic or company. Do not use for breaking news, paywalled pages or one known article (use blackwood_webpage_markdown). Returns JSON with a research briefing on a topic in one call: up to 3 recent GDELT news articles, each read and summarized, with source and link, below the price of separate calls for 0.04 USDC per call. Typical response time 15000 ms (p95). Category: Search. Price: US$0.04 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
hoursNoHow far back to look for news, in hours, 1 to 72 (24 when omitted), e.g. 48
topicYesTopic, company or person to research, e.g. stablecoin regulation
languageNoLanguage of the summaries (English when omitted), e.g. Portuguese

TDQS

A4.1/5.0
Behavior5/5

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

Beyond the annotations, the description discloses return shape (JSON with up to 3 summarized articles, each with source and link), cost (US$0.04 per call, framed against the price of separate calls), p95 latency of 15000 ms, and a payment path: a free demo credit, then the tool returns a command to pay from the caller's wallet. That payment flow is critical context an agent cannot glean from readOnlyHint=false alone. No contradiction — the wallet-payment behavior is consistent with a non-read-only hint.

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

Conciseness4/5

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

Well front-loaded: usage conditions first, exclusions second, return shape third, commercial terms last. There is some redundancy — the price is stated twice ('0.04 USDC per call' and 'Price: US$0.04 per call'), and the payment/demo-credit sentence is dense — but no sentence is wasted in substance.

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

Completeness4/5

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

With no output schema, the description does the necessary work by describing the returned JSON structure and the per-article fields, and the full input schema covers the parameters. What is missing is edge-case behavior (what comes back when no recent coverage exists) and explicit disambiguation from blackwood_news_search.

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

Parameters3/5

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

Schema description coverage is 100%, so topic, hours and language are already fully documented with ranges and examples. The description adds nothing parameter-specific (it does not mention the 1–72 hour window or the language option), so it sits at the baseline for a schema that carries the load.

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

Purpose4/5

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

The description names a specific output (a research briefing of recent press coverage on a topic or company) and states the scope of the result set (up to 3 recent GDELT articles, each read and summarized). It differentiates from blackwood_webpage_markdown and from breaking-news use, but never distinguishes itself from the close sibling blackwood_news_search, which an agent would plausibly confuse with this.

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

Usage Guidelines4/5

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

Explicit 'Use when...' followed by concrete 'Do not use for breaking news, paywalled pages or one known article (use blackwood_webpage_markdown)' gives both positive and negative conditions plus a named alternative. The gap is that the most likely alternative — blackwood_news_search — is never mentioned or contrasted, leaving that routing decision to inference.

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

blackwood_pdf_extractPDF to textA

Use when you need to extract text from a pdf, pdf to text or document parsing for an LLM. Do not use for scanned PDFs (no OCR), password-protected files or files over 15 MB. Returns JSON with PDF text extraction: the text of each page (first 20 pages) plus title, author and producer metadata for 0.0025 USDC per page, up to 0.05 USDC per call (clients without upto pay the cap). Result in the same call (about 10000 ms); a status tool polls for free if it takes longer. Category: Data. Price: US$0.05 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
urlYesPublic http(s) URL of the PDF file, e.g. https://example.com/report.pdf (up to 15 MB)

TDQS

A4.4/5.0
Behavior4/5

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

Rich beyond the annotations: discloses the 20-page cap, per-page and per-call pricing, a ~10 s synchronous wait with a free status-polling fallback for longer jobs, returned metadata fields, and the demo-credit/wallet payment flow. The one gap is that readOnlyHint=false is never explained — the tool is a paid call, so it would help to say the false flag reflects wallet spend rather than data mutation.

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

Conciseness4/5

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

Front-loaded with the use case and immediate exclusions, which is correct ordering. It is dense and mostly earns its space, but price is stated twice ('0.0025 USDC per page, up to 0.05 USDC per call' then 'Price: US$0.05 per call'), a small redundancy in an already long block.

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

Completeness5/5

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 fully compensates by naming the return shape (per-page text for the first 20 pages plus title/author/producer). Size limits, latency, payment and the polling escape hatch are all present, so an agent can call and interpret the result without further discovery.

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

Parameters3/5

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

Schema coverage is 100% and the single `url` parameter already documents the http(s) requirement, the example URL and the 15 MB cap; the description only restates the size limit. With the schema doing the heavy lifting, this earns the baseline rather than more.

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

Purpose5/5

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

Specific verb and resource ('extract text from a pdf'), plus a synonym framing ('pdf to text', 'document parsing for an LLM') that maps to how agents search. It is clearly distinguishable from siblings like blackwood_audio_transcribe and blackwood_webpage_markdown.

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

Usage Guidelines5/5

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

States when to use ('need to extract text from a pdf') and enumerates three explicit exclusions: scanned PDFs (no OCR), password-protected files, and files over 15 MB. That is exactly the when/when-not guidance an agent needs before paying for a call.

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

blackwood_qrcode_generateQR codeA

Use when you need a qr code generator for a URL, text, Wi-Fi or payment link as an SVG image. Do not use for reading or decoding an existing QR code, logos, colored codes or PNG output. Returns JSON with a QR code for your text or URL as SVG markup and an SVG data URL, with error correction level and border options, generated by the uqr library for 0.004 USDC per call. Typical response time 500 ms (p95). Category: Media. Price: US$0.004 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
eccNoError correction level: L 7%, M 15% (default), Q 25%, H 30%
textYesText or URL to encode, e.g. https://example.com (up to 2000 characters)
borderNoQuiet zone around the code, in modules (default 2)
pixelSizeNoSVG units per module (default 10)

TDQS

A4.6/5.0
Behavior5/5

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

Beyond annotations, the description discloses the return payload (SVG markup and data URL), supported options, generator library, per-call price, latency p95, and payment flow after free demo credit. It does not contradict the annotations: openWorldHint and non-idempotent billing behavior align with external QR generation.

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

Conciseness4/5

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

The definition is front-loaded with the use case and exclusions, then gives return, pricing, and payment context. It is efficient overall, though price is stated twice and the payment flow sentence is lengthy.

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

Completeness5/5

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

No output schema exists, so the description must explain returns; it does so by naming the JSON fields (SVG markup and SVG data URL) and noting options. For a simple four-parameter tool, this is complete enough to call correctly.

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

Parameters3/5

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

Schema coverage is 100%, so the input schema already documents text, ecc, border, and pixelSize fully. The description mentions error correction and border options but adds no syntax or defaults beyond the schema, and it does not mention pixelSize, so the baseline 3 is appropriate.

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

Purpose5/5

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

The description states a specific verb and resource: generating QR codes for URL, text, Wi-Fi, or payment link as SVG. It also explicitly distinguishes this from reading/decoding QR codes and from PNG/logo/colored variants, so an agent can identify its purpose without opening the schema.

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

Usage Guidelines5/5

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

It gives explicit when-to-use guidance ('Use when you need a qr code generator for...') and explicit exclusions ('Do not use for reading or decoding an existing QR code, logos, colored codes or PNG output'). No sibling QR tool exists, so the exclusions are the relevant alternatives.

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

blackwood_random_generateRandom numbersA

Use when you need a random number generator, dice rolls, a coin flip, a uuid or random bytes that no one can predict. Do not use for verifiable on-chain randomness (VRF) or reproducible seeded sequences. Returns JSON with cryptographically secure random values: integers in a range, dice rolls, coin flips, UUIDs or hex bytes, from the Workers Web Crypto CSPRNG for 0.005 USDC per call. Typical response time 500 ms (p95). Category: Infrastructure. Price: US$0.005 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
maxNointeger: highest value, inclusive (default 100)
minNointeger: lowest value, inclusive (default 1)
kindYesinteger (count values between min and max), dice (count rolls of a die with sides faces), coin (count flips), uuid (count UUID v4) or bytes (length random bytes as hex)
countNoHow many values (1-100, default 1); ignored for bytes
sidesNodice: faces of the die (default 6)
lengthNobytes: how many random bytes (1-256, default 32)

TDQS

A4.4/5.0
Behavior5/5

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

Far beyond what the annotations convey: it discloses the entropy source (Workers Web Crypto CSPRNG), guarantees unpredictability, states the return payload shape, the per-call price, p95 latency, and the payment flow including a free demo credit and the fallback command when the credit runs out. Annotations only cover read/write and open-world hints, so this description carries real operational context.

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

Conciseness4/5

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

Purpose and exclusions are front-loaded, then outputs, then operational facts. Slight redundancy: pricing appears twice ('0.005 USDC per call' and 'Price: US$0.005 per call'), and the payment-mechanics sentence is long, but every other clause earns its place.

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

Completeness5/5

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 specifies the return form ('JSON with cryptographically secure random values: integers in a range, dice rolls, coin flips, UUIDs or hex bytes') and covers cost, latency, and payment prerequisites. Nothing an agent needs to call it correctly is missing.

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

Parameters3/5

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

Schema coverage is 100% and each parameter already carries its own description with defaults and ranges, so the schema does the heavy lifting. The description maps the 'kind' values to output types (integers, dice, coin, uuid, bytes), which is a mild restatement rather than added semantics — baseline 3 applies.

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

Purpose5/5

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

The description opens with a specific use case and enumerates the exact outputs (integers in a range, dice, coin flips, UUIDs, hex bytes), making the resource and behavior unambiguous. It also distinguishes itself from the unrelated siblings by naming the two adjacent use cases it does NOT cover (VRF, seeded sequences).

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

Usage Guidelines4/5

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

It gives explicit when-to-use ('need a random number generator, dice rolls, a coin flip, a uuid or random bytes that no one can predict') and when-not-to-use ('verifiable on-chain randomness (VRF) or reproducible seeded sequences'). It does not name a specific alternative tool for those excluded cases, which keeps it just short of a 5 in a 33-sibling set.

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

blackwood_sec_factsSEC company financialsA

Use when you need company financials from SEC filings, earnings or fundamentals of a US company by ticker for the last two years. Do not use for quarterly numbers, real-time prices, non-US companies or filings older than two years. Returns JSON with SEC company financials for a US stock ticker from 10-K filings on SEC EDGAR: annual revenue, net and operating income, diluted EPS, cash flow and the balance sheet for 0.02 USDC per call. Typical response time 300 ms (p95). Category: Data. Price: US$0.02 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
tickerYesStock ticker of a company that files with the SEC, e.g. AAPL

TDQS

A4.1/5.0
Behavior3/5

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

The description adds genuinely useful behavioral context beyond the annotations: the return payload shape, a 300 ms p95 latency figure, and — most importantly — the payment model (0.02 USDC per call, free demo credit, then a wallet-settlement flow via AgentCash/Coinbase Agentic Wallet). That payment/credential flow is not expressible in the annotations and is critical for an agent to know. However, it repeats the price twice and never addresses rate limits, per-call failure modes, or why readOnlyHint is false for a purely reading tool, so it falls short of the top mark.

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

Conciseness3/5

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

The first two sentences are well front-loaded and earn their place, but the tail is padded: the price appears twice ('0.02 USDC per call' and 'Category: Data. Price: US$0.02 per call'), and the return description partially restates the opening sentence's 'earnings or fundamentals' phrasing. It is serviceable but not tight.

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

Completeness5/5

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

For a one-parameter, no-output-schema data tool, the definition covers everything an agent needs: what comes back (named financial fields, JSON), the temporal horizon, the latency budget, the monetary cost, and the exact payment/settlement path once free credit runs out. Nothing material is left for the caller to discover by failure.

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

Parameters3/5

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

Schema coverage is 100% and the single ticker parameter is already fully described with an example (AAPL) and a pattern. The description corroborates the semantics ('US company by ticker') but adds no syntax, exchange-suffix, or invalid-ticker handling detail beyond what the schema supplies, so the baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource — company financials from SEC filings (annual revenue, net/operating income, diluted EPS, cash flow, balance sheet) for a US ticker over the last two years. The scope and exclusions (no quarterly, no real-time prices, no non-US, no filings older than two years) make it unambiguously distinguishable from siblings like blackwood_company_dossier.

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

Usage Guidelines5/5

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

Explicit when-to-use clause plus a concrete negative list of four conditions that rule it out (quarterly numbers, real-time prices, non-US companies, filings older than two years). This is exactly the routing information an agent needs before picking among 33 siblings.

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

blackwood_speech_synthesizeText to speechA

Use when you need text to speech, tts, a voice audio file or spoken narration of a short text. Do not use for voice cloning, a chosen voice, SSML or audio longer than about two minutes. Returns JSON with text to speech (TTS): your text read aloud as WAV voice audio (base64, 44.1 kHz mono) by MeloTTS on Workers AI, in English, Spanish, French, Chinese, Japanese or Korean for 0.023 USDC per call. Typical response time 8000 ms (p95). Category: Media. Price: US$0.023 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
langNoSpeech language: en (default), es, fr, zh, ja or ko
textYesText to read aloud, e.g. Welcome to our store (up to 1000 characters)

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already flag this as non-read-only, non-idempotent, open-world, and non-destructive, and the description goes further with useful context the annotations cannot convey: model, output encoding (base64 WAV, 44.1 kHz mono), supported languages, p95 latency, and the pay-per-call flow including the free demo credit and the wallet payment fallback. However, it never says what a failure looks like or whether a repeated identical call is billed twice, which matters for a non-idempotent paid call.

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

Conciseness4/5

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

Well front-loaded: the trigger and exclusions come before the mechanics, which is the right order for tool selection. It loses a point for redundancy — the price appears twice (inline '0.023 USDC per call' and 'Price: US$0.023 per call') and 'text to speech (TTS)' is restated after already being named in the first sentence.

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

Completeness5/5

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

No output schema exists, so the description must describe return values — and it does precisely (JSON containing base64 WAV, 44.1 kHz mono). Combined with latency, cost, payment mechanics, and language coverage, an agent has everything needed to call this correctly and interpret the response.

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

Parameters3/5

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

Schema coverage is 100%, so both parameters are already documented including the language enum and the 1000-character cap. The description only adds the 'about two minutes' duration heuristic and the language list, which is marginal value over the schema. Baseline 3 applies.

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

Purpose5/5

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

States a specific verb (synthesize) and resource (speech audio) plus the exact deliverable: text read aloud as WAV by MeloTTS on Workers AI. It explicitly distinguishes itself from adjacent capabilities (voice cloning, chosen voice, SSML) so an agent can rule out the wrong tool immediately.

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

Usage Guidelines5/5

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

The opening sentence gives the trigger conditions (short text narration, voice audio file) and the next sentence gives explicit exclusions (no voice cloning, no voice selection, no SSML, nothing over ~2 minutes). That is a genuine when/when-not pair rather than implied usage.

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

blackwood_text_sentimentSentiment analysisA

Use when you need sentiment analysis, text sentiment or opinion mining of reviews, comments or headlines in English. Do not use for neutral or emotion labels, non-English text or aspect-level sentiment. Returns JSON with sentiment analysis of English text: a positive or negative label with a confidence score, from DistilBERT SST-2 on Workers AI, for one text or a batch of up to 20 for 0.004 USDC per call. Typical response time 1500 ms (p95). Category: Inference. Price: US$0.004 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
textNoOne English text to classify, e.g. The checkout was fast (up to 2000 characters)
textsNoOr a batch of up to 20 English texts, e.g. ["Great support", "Broken on arrival"]

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations by disclosing cost (0.004 USDC per call, batch of 20), latency (1500 ms p95), the model (DistilBERT SST-2 on Workers AI), and the payment flow including the free demo credit and wallet settlement path. readOnlyHint=false is consistent with a paid x402 call rather than a contradiction.

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

Conciseness4/5

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

Front-loaded with when-to-use and when-not-to-use before the mechanics, which is the right order. Slightly wasteful: the price appears twice ('0.004 USDC per call' and 'Price: US$0.004 per call'), and the second sentence packs many facts into one long clause.

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

Completeness5/5

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 explains the return shape (label + confidence, JSON), the input envelope (single or batch up to 20), latency and billing behavior. 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.

Parameters3/5

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

Schema coverage is 100%, so both parameters (text, texts) are already fully documented with types, limits and examples. The description restates 'one text or a batch of up to 20' but adds no format or edge-case semantics beyond the schema, so the baseline of 3 applies.

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

Purpose5/5

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

The description names a specific verb+resource (sentiment analysis / opinion mining of text) and scopes it to English reviews, comments and headlines. It also states the concrete output (positive/negative label with confidence) and the underlying model, making it clearly distinct from siblings like blackwood_text_summarize or blackwood_text_translate.

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

Usage Guidelines5/5

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

Explicit positive trigger ('Use when you need sentiment analysis...') and explicit exclusions ('Do not use for neutral or emotion labels, non-English text or aspect-level sentiment'). An agent can decide fit without opening the schema.

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

blackwood_text_summarizeSummarize textA

Use when you need to summarize text such as an article, notes or a transcript into a short summary. Do not use for uRLs or PDFs (extract the text first), exact quotes or citations. Returns JSON with a concise summary of the plain text you send (up to 20,000 characters): one short paragraph and key bullet points, written by IBM Granite 4.0 Micro on Workers AI for 0.008 USDC per call. Typical response time 8000 ms (p95). Category: Inference. Price: US$0.008 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
textYesPlain text to summarize, e.g. an article or a transcript (80 to 20,000 characters)
languageNoLanguage for the summary, e.g. English or Portuguese (default: the language of the text)
maxBulletsNoMost bullet points to return (1-10, default 5)

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: names the model (IBM Granite 4.0 Micro), the price (0.008 USDC), p95 latency (8000 ms), the payment path once the free demo credit runs out, and the input ceiling. The payment-on-failure behavior in particular is critical context an agent could not infer from readOnlyHint=false and openWorldHint=true.

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

Conciseness4/5

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

Front-loaded with the routing sentence, then behavior, then output, which is the right order. It loses a little by stating the price twice ('0.008 USDC per call' and 'Price: US$0.008 per call').

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

Completeness5/5

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

Despite no output schema, the description spells out the return shape (JSON with one short paragraph and key bullet points), the input bounds, and the payment failure path. An agent has everything needed to decide, call, and handle the paid-call outcome.

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

Parameters3/5

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

Schema description coverage is 100%, so text, language and maxBullets are already documented in the schema. The description only restates the 20,000-character limit and mentions bullets generically; it adds no syntax or defaulting detail for language or maxBullets beyond the schema.

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

Purpose5/5

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

States a specific verb and resource ('summarize text such as an article, notes or a transcript into a short summary') and pins down the output shape. It also differentiates from siblings by naming what it is not for (URLs, PDFs, exact quotes), which separates it from blackwood_webpage_markdown and blackwood_pdf_extract.

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

Usage Guidelines5/5

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

Explicit when-to-use plus explicit when-not-to-use with a remedy ('extract the text first'), which implicitly routes the agent to the extraction siblings. Exact quotes/citations are also excluded, closing off a plausible misuse.

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

blackwood_text_translateTranslate textA

Use when you need to translate text, a language translation or a text translation of a sentence or paragraph between two languages. Do not use for formatting that must be preserved, certified or legal translation, or speech (transcribe first). Returns JSON with text translation between about 100 languages by Meta M2M100 1.2B on Workers AI: the translated text with the source and target languages used for 0.012 USDC per call. Typical response time 5000 ms (p95). Category: Inference. Price: US$0.012 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
toYesTarget language as an ISO 639-1 code, e.g. es, fr, pt, de, ja, zh
fromNoSource language as an ISO 639-1 code (default en)
textYesText to translate, e.g. Pay only for the requests you make (up to 2000 characters)

TDQS

A4.1/5.0
Behavior3/5

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

Goes well beyond the annotations by disclosing price (US$0.012/call), model, p95 latency, the JSON return shape, and the demo-credit-then-pay-from-wallet flow. However, it does not describe what happens on unsupported language codes, truncation at the 2000-char limit, or failure modes. Solid added context, but not a rich behavioral account.

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

Conciseness3/5

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

Front-loaded with the use case and exclusions, which is good, but the opening is padded ('translate text, a language translation or a text translation of a sentence or paragraph') and the price is stated twice ('0.012 USDC per call' and 'Price: US$0.012 per call'), alongside a low-value 'Category: Inference' tag.

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

Completeness5/5

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 describing the returned JSON (translated text plus source/target languages). Combined with pricing, latency, and the payment fallback, an agent has everything needed to decide and invoke correctly.

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

Parameters3/5

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

Schema coverage is 100%, so `text`, `to`, and `from` (including the ISO 639-1 code format and the 2000-char limit) are already documented in the schema. The description adds only the model's 'about 100 languages' scope, which is a minor complement rather than new syntax or constraint detail. Baseline 3 is appropriate.

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

Purpose5/5

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

States a specific verb and resource ('translate text ... between two languages') and names the model (Meta M2M100 1.2B) that determines capability. It is clearly distinguishable from siblings like blackwood_text_summarize and blackwood_text_sentiment, and it explicitly routes speech input to blackwood_audio_transcribe first.

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

Usage Guidelines5/5

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

Gives explicit when-not conditions: formatting that must be preserved, certified/legal translation, and speech (transcribe first). The payment path is also spelled out (free demo credit, then a wallet-paid command), so an agent knows the prerequisite before calling.

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

blackwood_timezone_convertTime zonesA

Use when you need timezone conversion between time zones, the current time in a zone or a utc offset with daylight saving. Do not use for places given only by city or address without an IANA zone name, or dates before 1970. Returns JSON converting a date and time between IANA time zones with daylight saving rules, with UTC offsets, abbreviations and the current time in each zone, from the IANA tz database for 0.003 USDC per call. Typical response time 500 ms (p95). Category: Data. Price: US$0.003 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
toYesIANA time zones to convert to, e.g. ["Europe/London", "Asia/Tokyo"]
fromNoIANA time zone of a local time, e.g. America/Sao_Paulo (UTC when omitted)
timeNoDate and time to convert, ISO 8601: local wall time like 2026-10-17T15:30 (read in the from zone) or an instant with Z or an offset; now when omitted

TDQS

A4.8/5.0
Behavior5/5

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

Discloses substantial context beyond annotations: data source (IANA tz database), cost (0.003 USDC per call), p95 latency (500 ms), and the payment mechanic including the free demo credit and the wallet-payment fallback. The 402-style payment behavior is exactly the kind of trait an agent must know before invoking.

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

Conciseness4/5

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

Well front-loaded: usage rules first, return shape second, commercial/payment details last. Slight redundancy in repeating the price three times ('0.003 USDC per call', 'Price: US$0.003 per call', plus the demo-credit sentence), which costs a point.

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

Completeness5/5

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

With no output schema, the description steps in and describes the return payload: converted times, UTC offsets, abbreviations, and current time per zone. Combined with the domain limits and payment behavior, an agent has everything needed to call it correctly and interpret the result.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3; the description still adds real information by stating the IANA-zone requirement and the pre-1970 date limitation, which constrain acceptable parameter values. It does not explain the omitted-default behavior of `from`/`time` (covered in schema), so it stays below a 5.

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

Purpose5/5

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

States a specific verb and resource: converting a date/time between IANA time zones, plus the current time / UTC offset with daylight saving. No sibling tool overlaps this capability, so an agent can select it unambiguously from the 30+ tool list.

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

Usage Guidelines5/5

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

Front-loads 'Use when...' with three concrete triggers and follows with explicit exclusions ('Do not use for places given only by city or address without an IANA zone name, or dates before 1970'). These exclusions are the practical failure modes an agent would otherwise hit.

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

blackwood_token_priceToken price on BaseA

Use when you need a crypto token price or market data for a Base token, quoted from on-chain liquidity. Do not use for tokens that only trade off Base or on other DEXs (Aerodrome is not read), price history or OHLC. Returns JSON with the USD price of a token on Base computed on-chain from its deepest Uniswap v3 pool against USDC or WETH, with pool, fee tier and depth for 0.003 USDC per call. Typical response time 1200 ms (p95). Category: Trading. Price: US$0.003 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
tokenYesToken on Base: contract address (0x...) or a symbol like WETH, cbBTC, AERO, DEGEN, VIRTUAL

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: names the data source (deepest Uniswap v3 pool vs USDC/WETH), the returned fields (price, pool, fee tier, depth), the cost (0.003 USDC per call), the p95 latency (1200 ms), and the payment fallback once the free demo credit runs out. The readOnlyHint=false annotation is consistent with a paid call that can consume wallet funds, and the description explains that mechanism.

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

Conciseness4/5

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

Front-loads usage and exclusions, then behavior, then pricing — good ordering. However, the cost is stated twice ('0.003 USDC per call' and 'Price: US$0.003 per call') and the 'Category: Trading' tag adds little, so a small trim would improve it.

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

Completeness5/5

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

No output schema exists, but the description enumerates the returned JSON contents (USD price plus pool, fee tier, depth), states the quote mechanism, latency, cost and payment flow. An agent has everything needed to call it and interpret the result.

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

Parameters3/5

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

Schema description coverage is 100%, and the single `token` parameter already documents address-or-symbol input with examples (WETH, cbBTC, AERO). The description adds nothing about the parameter itself — it only mentions the USDC/WETH quote leg — so the baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource ('crypto token price or market data for a Base token, quoted from on-chain liquidity') and pins the scope to Base, which distinguishes it from siblings like blackwood_wallet_value, blackwood_fx_rates and blackwood_altcoin_discovery. An agent can tell what it returns without opening the schema.

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

Usage Guidelines5/5

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

Explicitly names when not to use it: tokens that only trade off Base, other DEXs ('Aerodrome is not read'), and price history/OHLC. That is a rare level of exclusion guidance and directly routes the agent away from misuse.

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

blackwood_wallet_balancesWallet balances on BaseA

Use when you need a wallet balance, token balances or the ERC20 balance of an address on Base, read live from the chain. Do not use for ethereum mainnet or other chains, NFTs, transaction history or USD values. Returns JSON with the wallet balance of an address on Base: ETH and ERC20 token balances read on-chain in one block, 21 major tokens plus any you list for 0.004 USDC per call. Typical response time 1200 ms (p95). Category: Data. Price: US$0.004 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
tokensNoExtra ERC20 token addresses on Base to check, e.g. ["0x4200000000000000000000000000000000000006"] (up to 20, beyond the 21 major ones)
addressYesWallet address on Base, e.g. 0x5A6c77758820182484EA8DE614FC65423E80749a
includeZeroNoAlso list tokens with zero balance (false when omitted)

TDQS

A4.4/5.0
Behavior5/5

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

The description adds substantial behavioral context beyond the annotations: cost per call, latency, one-block on-chain read, 21 major tokens plus up to 20 extra tokens, free demo credit, and post-credit payment behavior. The readOnlyHint=false annotation is not contradicted; the paid-call flow can plausibly account for non-read-only side effects.

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

Conciseness4/5

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

The description is front-loaded with usage guidance and then supplies return, pricing, and latency details. It is mostly efficient, though pricing is mentioned twice and the payment-credit sentence is somewhat long.

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

Completeness5/5

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 explains the return shape (JSON with ETH and ERC20 balances), token coverage, latency, cost, and payment flow. For a 3-parameter read tool, this is complete enough for an agent to invoke it confidently.

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

Parameters3/5

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

Schema description coverage is 100%, so parameter meaning is already well documented. The description adds the useful detail that 21 major tokens are included and extra tokens can be listed, but it does not expand on includeZero or the token address format beyond the schema.

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

Purpose5/5

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

The description states a specific verb and resource: reads wallet, token, or ERC20 balances for an address on Base, live from chain. It also distinguishes the tool from adjacent use cases by excluding Ethereum mainnet, other chains, NFTs, transaction history, and USD values, which helps separate it from wallet_value and wallet_portfolio.

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

Usage Guidelines4/5

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

It gives clear when-to-use and when-not-to-use guidance, including chain, asset type, and USD-value exclusions. It does not explicitly name the sibling alternatives it routes to, so it falls short of the highest level.

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

blackwood_wallet_portfolioWallet portfolio and historyA

Use when you need a multi-chain wallet balance, a wallet portfolio or wallet transaction history on Ethereum, Base or Solana. Do not use for uSD values, NFTs, DeFi positions, long-tail tokens or chains beyond Ethereum, Base and Solana. Returns JSON with a multi-chain wallet balance and transaction history: native and major-token balances on Ethereum, Base or Solana plus the latest transfers, without airdrop spam for 0.005 USDC per call. Typical response time 3000 ms (p95). Category: Data. Price: US$0.005 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
chainsNoChains to read (ethereum and base for a 0x address, solana for a Solana address, when omitted), e.g. ["base"]
addressYesWallet address: 0x... for Ethereum and Base, or a Solana address, e.g. 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
historyLimitNoLatest transfers to return per chain, 0 to 25 (10 when omitted), e.g. 5

TDQS

A4.2/5.0
Behavior3/5

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

Annotations already declare openWorldHint=true, destructiveHint=false, idempotentHint=false, so the safety profile is partly covered. The description adds genuinely useful behavior: 0.005 USDC cost, free demo credit, the payment flow via AgentCash/Coinbase Agentic Wallet, 3000 ms p95 latency, and airdrop-spam filtering. These are real additions beyond the annotations, though the return shape is described only loosely and the readOnlyHint=false flag is left unexplained.

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

Conciseness4/5

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

Front-loaded with 'Use when...' followed by the exclusion list and output summary, which is good ordering. The pricing/payment/credit sentences are somewhat boilerplate-heavy for a tool description but do carry real invocation-relevant information, so only a minor deduction.

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

Completeness5/5

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

Given no output schema and three well-documented params, the description covers what is returned (native and major-token balances plus latest transfers), latency expectations, and crucially the paid-call mechanic that would otherwise surprise an agent. 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.

Parameters3/5

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

Schema description coverage is 100%, and the schema already documents chains, address formats, and historyLimit defaults and ranges. The description mentions the chains parameter indirectly but adds no syntax or format detail beyond the schema, so baseline 3 applies.

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

Purpose5/5

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

The first sentence names the specific resource (multi-chain wallet balance, portfolio, transaction history) and enumerates the supported chains, which is exactly what an agent needs to distinguish this from siblings like blackwood_wallet_balances and blackwood_wallet_value. The negative clause ('Do not use for uSD values, NFTs, DeFi positions...') further sharpens the boundary.

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

Usage Guidelines5/5

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

Explicit when-to-use ('multi-chain wallet balance... on Ethereum, Base or Solana') and when-not-to-use (uSD values, NFTs, DeFi positions, long-tail tokens, other chains). Alternatives are implied by naming the excluded categories, leaving little ambiguity about tool selection.

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

blackwood_wallet_valueWallet value in USDA

Use when you need a wallet portfolio value in USD, a wallet net worth or token balances with USD value for a 0x address. Do not use for solana wallets, transaction history, NFTs, DeFi positions or long-tail tokens. Returns JSON with a wallet's USD value on Ethereum and Base in one call: native and major-token balances priced on-chain from Uniswap v3 pools on Base, per-chain totals and the tokens left unpriced for 0.005 USDC per call. Typical response time 5000 ms (p95). Category: Trading. Price: US$0.005 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
chainsNoChains to value (ethereum and base when omitted), e.g. ["base"]
addressYesWallet address (0x...) on Ethereum and Base, e.g. 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

TDQS

A4.1/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses the pricing model (0.005 USDC per call, free demo credit, then an x402 payment command returned to the caller), latency (5000 ms p95), data provenance (Uniswap v3 pools on Base), and that unpriced long-tail tokens are surfaced rather than silently dropped. These operational traits are exactly what an agent needs before committing to a paid call.

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

Conciseness4/5

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

Front-loaded with the use-case sentence and the exclusion list before moving into return shape, latency, and pricing. Most sentences earn their place, though the category/price/demo-credit footer is somewhat verbose boilerplate.

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

Completeness4/5

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

With no output schema and only two params, the description carries adequate weight: it describes the returned JSON (native and major-token balances, per-chain totals, unpriced tokens), states coverage limits, cost, and latency. The one real deficiency is the missing comparison against the near-identical wallet_balances and wallet_portfolio siblings.

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

Parameters3/5

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

Schema description coverage is 100%, so both parameters (address and the chains enum array) are already fully documented in the schema, including the default of both chains when omitted. The description only restates the Ethereum/Base scope and adds no new syntax or constraint detail, so the baseline 3 applies.

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

Purpose4/5

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

The description states a specific verb and resource: retrieve a wallet's USD portfolio value/net worth with priced token balances for a 0x address, on Ethereum and Base. It is clear what the tool does, but it never distinguishes itself from the very similar siblings blackwood_wallet_balances and blackwood_wallet_portfolio, so an agent still has to guess which of the three to pick.

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

Usage Guidelines4/5

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

It gives explicit triggering conditions ("Use when you need a wallet portfolio value in USD... or token balances with USD value for a 0x address") and explicit exclusions (no Solana, transaction history, NFTs, DeFi positions, long-tail tokens). That is strong when/when-not guidance, but it never names an alternative tool to use instead for the excluded cases.

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

blackwood_weather_forecastWeather forecastA

Use when you need a weather forecast, the current weather, temperature, rain or wind for the next hours or days at given coordinates. Do not use for historical weather, severe weather alerts or places given only by name (geocode first). Returns JSON with the weather forecast for a latitude and longitude: hourly temperature, rain and precipitation, wind, humidity and cloud cover for the next days, from MET Norway for 0.003 USDC per call. Typical response time 1500 ms (p95). Category: Data. Price: US$0.003 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
hoursNoHow many hours ahead to return (1-240, 48 when omitted); hourly at first, then every 6 hours
latitudeYesLatitude in decimal degrees (WGS84), e.g. 59.9139 for Oslo, rounded to 4 decimals
longitudeYesLongitude in decimal degrees (WGS84), e.g. 10.7522 for Oslo, rounded to 4 decimals

TDQS

A4.6/5.0
Behavior5/5

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

Goes well beyond the annotations: discloses the data source (MET Norway), the per-call price, that a free demo credit covers first calls, and — critically — that after that the tool returns a payment command rather than data, requiring AgentCash or a Coinbase Agentic Wallet. It also gives p95 latency (~1500 ms), which the agent needs for timeout planning. No contradiction with annotations; the paid-call model is consistent with readOnlyHint=false and idempotentHint=false (repeat calls cost money).

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

Conciseness4/5

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

Usage constraints are front-loaded in the first two sentences, which is good structure. However, the price is stated twice ('0.003 USDC per call' and 'Price: US$0.003 per call') and the 'Category: Data' label is dead weight. Still, most sentences carry information an agent needs before paying for a call.

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

Completeness5/5

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

For a 3-parameter, no-output-schema tool the description closes all the gaps: what is returned (field list and time horizon), where the data comes from, how much it costs, how payment works, and how long it takes. An agent has everything required to call it and to handle the post-credit payment response.

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

Parameters3/5

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

Schema description coverage is 100%, so latitude, longitude and hours are already fully documented in the schema, including ranges, format and the hourly-then-6-hourly behaviour. The description only restates 'at given coordinates' and 'for the next hours or days', adding nothing new. Baseline 3 is correct.

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

Purpose5/5

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

States a specific verb+resource (retrieve a weather forecast and current conditions) and enumerates the returned quantities (temperature, rain, wind, humidity, cloud cover) for a coordinate pair. It is unambiguously distinct from every sibling, none of which touch weather (airport_delays is the closest neighbour and is clearly different).

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

Usage Guidelines5/5

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

Explicitly names when to use it (forecast/current conditions for next hours or days at coordinates) and three exclusions: historical weather, severe weather alerts, and place-name lookups ('geocode first'). This is exactly the when/when-not/alternative structure that lets an agent route correctly.

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

blackwood_webpage_markdownWeb page to MarkdownA

Use when you need web page to markdown, url to markdown, to scrape a web page or extract content from a url for an LLM. Do not use for pages that need JavaScript to render, sit behind a login or paywall, or are not HTML (PDFs go to blackwood_pdf_extract). Returns JSON with the clean Markdown of a public web page (URL to Markdown, boilerplate stripped) plus its title, description, language, canonical URL and links for 0.01 USDC per call. Typical response time 2500 ms (p95). Category: Data. Price: US$0.01 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
urlYesPublic http(s) URL of the web page to read, e.g. https://example.com/article
maxCharsNoMaximum length of the returned markdown (500-100000 characters, 50000 when omitted)

TDQS

A4.6/5.0
Behavior5/5

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

Annotations mark openWorldHint=true and readOnlyHint=false, and the description explains the otherwise puzzling non-read-only flag: the call costs 0.01 USDC and requires a payment flow (free demo credit, then a wallet-pay command). It also discloses the return payload (markdown, title, description, language, canonical URL, links) and latency (2500 ms p95) — genuinely additive context beyond the annotations.

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

Conciseness4/5

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

Well front-loaded: use case first, exclusions second, returns and pricing last. It loses a point for redundancy — the price appears twice ('0.01 USDC per call' and 'Price: US$0.01 per call') and the 'Category: Data' tag adds nothing an agent can act on.

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

Completeness5/5

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 specifies the return shape (JSON with markdown plus metadata fields), the cost, the latency, the free-credit/payment transition, and the rendering/login limits. An agent has everything needed to decide whether to call and what to expect, with no return-format guesswork.

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

Parameters3/5

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

Schema description coverage is 100%, so both `url` and `maxChars` (with its 500–100000 range and 50000 default) are fully documented in the schema. The description adds no syntax, format, or truncation guidance beyond that. A 3 is the correct baseline when the schema already carries the parameter burden.

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

Purpose5/5

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

The description opens with a specific verb+resource ('web page to markdown, url to markdown, scrape a web page or extract content from a url') and immediately names the sibling it is not ('PDFs go to blackwood_pdf_extract'). An agent can distinguish it from the other 30+ blackwood tools without opening the schema.

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

Usage Guidelines5/5

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

Explicit when-to-use ('extract content from a url for an LLM') plus three concrete when-not conditions: JavaScript-rendered pages, login/paywall content, and non-HTML. It also routes the excluded case to the correct alternative, blackwood_pdf_extract, so the agent knows exactly where to go next.

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

blackwood_x402_checkx402 endpoint checkA

Use when you need an x402 endpoint check or x402 endpoint test, or to validate x402 endpoint listings before paying or integrating. Do not use for actually paying the endpoint, or endpoints behind authentication. Returns JSON with an x402 check of an endpoint without paying: whether it answers 402, its payment options (scheme, network, asset, amount, payTo), Bazaar metadata and problems found for 0.007 USDC per call. Typical response time 2500 ms (p95). Category: Infrastructure. Price: US$0.007 per call. A small free demo credit covers the first calls; after that the tool returns the command that pays the call from your own wallet (AgentCash or Coinbase Agentic Wallet).

NameRequiredDescriptionDefault
urlYesPublic http(s) URL of the x402 endpoint, e.g. https://x402.org/protected
bodyNoJSON body to send with POST, e.g. {"url": "https://example.com"} (no payment is ever attached)
methodNoHTTP method of the endpoint (GET when omitted)

TDQS

A4.4/5.0
Behavior4/5

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

Adds real context beyond annotations: call cost (0.007 USDC), p95 latency of 2500 ms, a free demo credit cap, and the important behavior that after credit exhaustion the tool returns a payment command rather than performing the call. readOnlyHint=false is consistent with a tool that incurs a paid invocation; nothing contradicts it. Minor gap: it doesn't say whether a failed check is still billed.

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

Conciseness4/5

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

Front-loaded with the trigger and the exclusion, then cost and latency. Slight redundancy in the opening ('x402 endpoint check or x402 endpoint test') reads as keyword padding, and pricing appears twice (in prose and again as 'Price: US$0.007 per call').

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

Completeness5/5

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

No output schema exists, but the description enumerates the return contents: 402 status, payment options with scheme/network/asset/amount/payTo, Bazaar metadata, and detected problems. Combined with the cost and credit-exhaustion behavior, an agent has everything needed to decide and call.

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

Parameters3/5

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

Schema coverage is 100%, so url, body, and method are already documented with examples and an enum. The description adds no parameter-level detail (e.g. how body interacts with method, or size/timeout limits), so the baseline 3 applies.

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

Purpose5/5

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

States a specific verb and resource ('x402 endpoint check… validate x402 endpoint listings') and immediately scopes it against the adjacent action an agent might confuse it with ('Do not use for actually paying the endpoint'). Among siblings like blackwood_wallet_balances or blackwood_token_price, this is unambiguously a pre-payment diagnosis tool.

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

Usage Guidelines5/5

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

Explicit positive trigger ('when you need an x402 endpoint check… before paying or integrating') and two explicit exclusions (actually paying; endpoints behind authentication). That is when-to-use, when-not-to-use, and the alternative framing in one place.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 34 tool updatesv0.2.0
    • First observedblackwood_account
    • First observedblackwood_airport_delays
    • First observedblackwood_altcoin_discovery
    • First observedblackwood_audio_transcribe
    • First observedblackwood_company_dossier
    • First observedblackwood_crypto_news
    • First observedblackwood_domain_intel
    • First observedblackwood_email_batch
    • First observedblackwood_email_check
    • First observedblackwood_ens_lookup
    • First observedblackwood_fx_history
    • First observedblackwood_fx_rates
    • First observedblackwood_gas_fees
    • First observedblackwood_headers_audit
    • First observedblackwood_image_generate
    • First observedblackwood_llm_chat
    • First observedblackwood_news_briefing
    • First observedblackwood_news_search
    • First observedblackwood_pdf_extract
    • First observedblackwood_qrcode_generate
    • First observedblackwood_random_generate
    • First observedblackwood_sec_facts
    • First observedblackwood_speech_synthesize
    • First observedblackwood_text_sentiment
    • First observedblackwood_text_summarize
    • First observedblackwood_text_translate
    • First observedblackwood_timezone_convert
    • First observedblackwood_token_price
    • First observedblackwood_wallet_balances
    • First observedblackwood_wallet_portfolio
    • First observedblackwood_wallet_value
    • First observedblackwood_weather_forecast
    • First observedblackwood_webpage_markdown
    • First observedblackwood_x402_check

TDQS

A4.1/5.0

Scored across 34 tools

Disambiguation4/5

Most tools have clearly distinct purposes, especially across data, media, inference, trading and infrastructure categories. A few clusters—wallet_balances vs wallet_portfolio vs wallet_value, and news_search vs news_briefing vs crypto_news—could be confused at first glance, but the descriptions sharply define chain, scope and output differences.

Naming Consistency5/5

Every tool uses the same blackwood_ prefix followed by descriptive snake_case, with no mixed casing or erratic verb styles. Even where the name is noun-first rather than verb_noun, the convention is predictable and readable throughout.

Tool Count2/5

At 34 tools, the surface is well past the typical 3–15 range and feels heavy for an agent to navigate. While it is an API marketplace and each endpoint is individually scoped, the set is large enough that discovery and selection burden is significant.

Completeness4/5

The toolkit broadly covers its apparent purpose as a paid utility API marketplace: account, web/data, media, inference, crypto/trading, wallets and infrastructure. There are still minor gaps, such as OCR, deeper market history, geocoding and several common utility APIs, but no severe dead end for the stated broad scope.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    C
    maintenance
    Trust layer for AI agents: 22 pay-per-call x402 tools for scam and fraud checks, payment pre-flight, wallet screening, policy approvals, contact extraction and company research. Free preview with no wallet; paid calls settle in USDC on Base.
    22
    80 npm
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    Provides AI agents with 10 pay-per-call utility tools (QR generation, DNS lookup, OCR, etc.) using USDC on Base via the x402 protocol, with agent's private key never leaving the agent.
    11
    55 npm
    MIT
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to access 11 paid x402 endpoints as standard MCP tools, paying per call in USDC on Base without API keys, covering chat, code, vision, embeddings, crypto prices, weather, geolocation, forex, and WHOIS data.
    -
  • A
    license
    A
    quality
    B
    maintenance
    Pay-per-call data and tools for AI agents over x402, by UnyKorn. 360 endpoints: DeFi and market data, multi-chain wallet reads, wallet and token risk signals, SEC filings, web and domain intel, and AI text tools. Settled per call in USDC on Base ($0.001-$0.25). No API keys or subscriptions; unpaid calls return the exact quote first.
    21
    MIT