Diogenes Web3, DeFi & 402 Security MCP

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, closed-world), and the description adds operational traits an agent could not infer: 32 KB input ceiling, 60 RPM limit, demo-mode flag versus L402 payment of 45 sats, and HTTP 400 on invalid input. That is exactly the kind of context annotations cannot express.

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

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

One dense paragraph, front-loaded with purpose and the sibling routing rule. The pricing/rate-limit clause is crammed into the same sentence and slightly blurs the scan, but no sentence is wasted.

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

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

For a two-parameter read tool with an output schema, rich annotations, and 100% schema coverage, nothing needed for correct invocation is missing: scope, exclusions, cost model, rate limit, and failure mode are all present.

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

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

Schema coverage is 100%, so baseline is 3; the description modestly adds value by restating the 'chain' default and the accepted forms of 'code_or_address' (source, ABI, or address), which clarifies that an address is valid input. It does not enumerate the enum values beyond the schema, so it stays a step short of full marks.

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

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

Specific verb ('Statically audits') plus concrete resource ('Solidity, Vyper, or Move smart contract source code') and an enumerated threat list (honeypot transfer taxes, hidden mint backdoors, proxy upgrade traps, reentrancy). It also explicitly carves itself out from the sibling scan_solana_cpi_reentrancy, so an agent can disambiguate 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.

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

States the trigger ('before deploying or interacting with a protocol') and names the exact alternative with the condition that selects it ('for scanning Solana Anchor/Rust programs... use scan_solana_cpi_reentrancy instead'). Both when-to-use and when-to-use-something-else are explicit.

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

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

Goes well beyond the annotations (which already establish readOnly/idempotent/non-destructive) by disclosing statelessness, a 32 KB payload cap, a 60 RPM rate limit, the '?demo=true' and L402 (20 sats) access paths, and the HTTP 400 failure mode. These are operational traits an agent cannot infer from structured fields.

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

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

Three tight sentences, front-loaded with purpose before usage and then operational constraints; nothing is repeated from the annotations. Slight density cost from bundling rate limit, payment scheme, and error code into one sentence, but each clause carries distinct information.

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

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

For a stateless two-parameter read with an output schema (so return shape need not be described), the description covers access modes, limits, and failure behavior adequately. The only real gap is the muddled statement about the amount default, which leaves a caller unsure of the exact fallback value.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description's parenthetical 'amount' defaults to 'standard'' conflicts with the schema, which documents 'defaults to 100 when omitted'. That is confusing rather than additive, and 'standard' is not a value in the numeric amount domain; the only real gain is naming the 'currency' argument.

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

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

States a specific verb ('Calculates') and resource ('instantaneous spot exchange rates and equivalent USD, BTC, and satoshi values'), and enumerates the supported assets. It also explicitly names the sibling it is not (compare_crosschain_bridge_routes), so an agent can disambiguate without opening either schema.

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

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

Gives a concrete when-to-use trigger ('converting a token amount into USD or satoshis for invoice pricing or accounting') and an explicit alternative with its own condition ('for quoting executable non-KYC cross-chain bridge routes... use compare_crosschain_bridge_routes instead'). Both the positive and negative selection cases are covered.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, and the description adds substantial context beyond that: stateless edge call, 32 KB max, 60 RPM limit, demo mode or L402 payment (20 sats), and HTTP 400 on invalid input. It also clarifies that from_asset is the required input and to_asset defaults to BTC_NATIVE.

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

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

Two dense sentences with no wasted words. The comparison scope and differentiator are front-loaded ahead of operational details, so the agent gets the key routing decision first.

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

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

Given an output schema, 100% parameter coverage, and rich annotations, the description fills the remaining gaps: target use case, alternative tool, access/payment model, rate limits, and error behavior. Nothing an agent needs to select or invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the baseline is 3 even with no parameter detail in the description. The description does mention from_asset and to_asset defaults, but that information duplicates what the schema already documents; it does not add new semantics such as amount formatting or enum constraints.

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

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

States a specific verb ('Compares') plus the exact resource (non-KYC cross-chain swap routes across THORChain, Maya, and Liquid) and the metrics compared (bp fee, net output sats, settlement time). It also explicitly distinguishes itself from the sibling calculate_spot_swap_rate, so an agent can tell them apart without opening either schema.

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

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

Gives an explicit use case ('routing cross-chain treasury settlements, e.g. Solana USDC or Base ETH into native Bitcoin') and names the alternative tool with the condition that selects it ('for calculating mid-market spot exchange rates without bridge routing fees, use calculate_spot_swap_rate instead'). Nothing is left to inference.

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

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

Beyond the annotations (readOnly/idempotent/non-destructive), it discloses operational traits the agent cannot see elsewhere: stateless edge call, 32 KB payload cap, 60 RPM throttle, L402 payment option, demo mode, and HTTP 400 on invalid input. The only defect is that one of these operational details is wrong (see parameter note), so it stops just short of full trust.

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

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

Purpose, verification targets, and the sibling alternative are front-loaded before the operational constraints. Dense but essentially waste-free; the final clause (demo/L402/400) is slightly crammed into one sentence, which is the only reason it is not a 5.

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

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

Output schema exists, so return values need no explanation, and the description fully covers scope, safety profile, alternatives, and limits. It is near-complete for a 2-parameter read tool, with the chain_id default conflict the one gap that matters to correct invocation.

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

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

Schema coverage is 100%, so the baseline would be 3, but the description actively contradicts the schema: it says 'chain_id' defaults to '1' while the schema says it defaults to '8453' (Base). Since chain_id governs which canonical router spender addresses are used for verification, this error can cause a wrong-chain approval to be judged safe. It also references a '?demo=true' query flag that appears in neither parameter.

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

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

States a specific verb ('Decodes') plus the exact resource ('EIP-712 and Uniswap Permit2 off-chain typed-data payloads') and the outputs of interest (spender identity, uint256.max approvals, expired deadlines). It also contrasts itself with the sibling simulate_evm_transaction_calldata, so an agent can separate the off-chain signing case from raw calldata without opening either schema.

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

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

Explicit when-to-use ('inspecting an off-chain eth_signTypedData_v4 or Permit2 payload before signing') and an explicit when-not with the named alternative and its condition ('raw on-chain hex transaction calldata (0x...) for eth_sendTransaction, use simulate_evm_transaction_calldata instead'). Nothing is left to inference.

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

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

Annotations already declare readOnly/idempotent/non-destructive/closed-world, and the description goes well beyond them: max 32 KB payload, 60 RPM rate limit, stateless edge call, L402 pricing (20 sats), '?demo=true' bypass, and HTTP 400 on invalid input. These operational traits are exactly what an agent needs before calling an edge endpoint; the only gap is that index/latency behavior is left to the output schema.

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

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

Three tight sentences ordered purpose → when/alternative → operational limits, with zero filler. The final sentence is dense (size, rate, payment, error code all crammed into one clause chain) and could be split for scanability, which keeps it from a 5.

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

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

For a 2-parameter stateless lookup with an output schema and full annotation coverage, the description supplies everything else an agent needs: what it detects, when to call it, the alternative, resource limits, payment model, and failure behavior. Nothing material is missing.

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

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

Schema description coverage is 100%, so both parameters are already documented with enum values and defaults. The description restates that 'address_standard' defaults to 'auto_detect' and surfaces an out-of-schema '?demo=true' flag, but adds no format or validation syntax beyond the schema. Baseline 3 is correct when the schema does the heavy lifting.

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

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

The first sentence states a specific verb and resource (compares a recipient wallet address against recent transaction history) and names the two exact threat classes it detects: vanity prefix/suffix lookalike spoofing and zero-value dusting. It also names the sibling tool it is not (simulate_evm_transaction_calldata), so an agent can route without opening either schema.

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

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

Explicit trigger: 'Use when verifying a recipient EVM or Solana wallet address before sending funds.' It provides an exclusion plus a concrete alternative ('for decoding hex smart contract calldata payloads, use simulate_evm_transaction_calldata instead'), 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.

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

Goes well beyond the readOnly/idempotent/openWorld annotations: declares statelessness, a 32 KB payload cap, 60 RPM rate limit, demo-mode bypass, L402 payment of 10 sats, and HTTP 400 on invalid input. These are operational facts an agent cannot infer from the annotations or schema.

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

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

Three sentences, front-loaded with purpose, then routing guidance, then operational constraints. Dense but every clause is functional; the parenthetical '(max 32 KB, 60 RPM)' is compressed rather than verbose, though the sentence is somewhat overloaded.

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

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

Output schema exists so return shape needn't be described, and annotations cover the safety profile. Description fills the remaining gaps an agent needs: auth mechanics (L402/demo), rate/payload limits, error behavior, and sibling routing. Nothing material is missing.

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

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

Schema coverage is 100% and the sole parameter already documents the enum and the 'half_hour' default, so the schema carries the load. The description reinforces meaning by naming the tiers (fastest, half-hour, hour, economy) in the context of confirmation speed, adding slight framing value over the raw enum values.

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

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

Names a specific verb (Fetches) and resource (Bitcoin mainnet mempool feerate recommendations) with the exact unit (sat/vB) and the four confirmation tiers enumerated. An agent can distinguish it immediately from estimate_solana_priority_fees and plan_bitcoin_utxo_consolidation.

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

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

Explicitly states the use case ('before broadcasting an on-chain BTC transaction') and names the alternative with the condition that selects it ('for calculating exact SegWit/Taproot UTXO batch consolidation vByte weights and dust thresholds, use plan_bitcoin_utxo_consolidation instead'). Both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and non-destructive, so the safety profile is covered. The description still adds real operational context beyond that: statelessness, a 32 KB payload cap, 60 RPM rate limit, demo mode or x402 payment of 10 sats, and an HTTP 400 on invalid input. However, it never says what 'optimal' means or which chain/endpoint is actually called, so it is good rather than exemplary.

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

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

Purpose is front-loaded in the first sentence, usage and exclusion in the second, operational constraints last — a logical order with no filler. The final clause is a run-on cramming statelessness, size cap, rate limit, payment modes and error code into one sentence, which costs some readability.

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

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

With an output schema present, return values need not be described, and the description covers rate limits, size limits, payment/auth paths and failure behavior for a read-only edge call. The one substantive gap is the tx_type default mismatch and the unspecified definition of 'optimal' estimation.

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

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

Schema coverage is 100% with both enums documented, so the baseline would be 3. But the description asserts 'tx_type' defaults to 'simple_transfer', while the schema explicitly says it defaults to 'dex_swap' when omitted — the description actively introduces conflicting parameter semantics rather than merely restating them.

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

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

States a specific verb and resource ('Calculates ... compute-unit microlamport priority fees and Jito bundle tip lamports') plus the objective (target block-inclusion probability). It also explicitly distinguishes itself from the nearest sibling, estimate_bitcoin_mempool_fees, so an agent can route without opening either schema.

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

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

Gives an explicit use condition ('when setting SetComputeUnitPrice and Jito tips before broadcasting a Solana transaction') and an explicit when-not with the named alternative ('for querying Bitcoin L1 sat/vB mempool fee rates, use estimate_bitcoin_mempool_fees'). Nothing about selection is left to inference.

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

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

Beyond annotations, the description adds operational context including response size (32 KB), rate limit (60 RPM), demo vs L402 payment access, and HTTP 400 on invalid input. These details help an agent plan calls without guessing about access, rate limits, or error behavior.

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

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

The description is front-loaded with purpose and usage guidance, then packs operational details tightly without wasting sentences. Every clause contributes either selection guidance or invocation context.

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

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

Given the output schema exists, the description need not explain return values. It covers purpose, when to use it, the main alternative, access/payment mechanics, rate limits, defaults, and error handling, making it complete for correct invocation.

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

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

Schema description coverage is 100%, so the schema already documents both parameters and the execution_venue enum. The description only repeats that it accepts 'pair' and that execution_venue defaults to 'uniswap_v3_public', adding little semantic value beyond the schema.

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

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

The description names a specific verb, resource, and scope: it evaluates DEX swap parameters against pool depth and mempool visibility to quantify MEV sandwich risk and compute optimal slippage tolerance. It also explicitly distinguishes itself from compare_crosschain_bridge_routes.

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

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

It states exactly when to use the tool: configuring slippage tolerance and private-RPC routing before executing an on-chain DEX swap. It also names the alternative tool and condition for cross-chain bridge route comparison.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive behavior, and closed-world scope. The description adds valuable operational context beyond annotations: statelessness, a 32 KB limit, 60 RPM rate limit, demo/L402 payment options, and HTTP 400 on invalid input, with no contradiction.

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

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

The description is front-loaded with the core purpose and the sibling differentiation before operational details. Despite being information-dense, each clause contributes useful selection or invocation context, and there is no filler.

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

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

For a stateless two-parameter evaluator with an output schema, the description covers purpose, sibling routing, input expectations, rate/size limits, payment modes, and error behavior. An agent has enough information to select and invoke it correctly without needing return-value documentation.

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

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

Schema description coverage is 100%, so both parameters and the risk_profile enum are already well documented. The description reiterates the default risk_profile and token_address input but adds only marginal meaning beyond the schema's own parameter descriptions.

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

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

The description states a specific verb and resource: evaluating a Solana SPL token's rug-pull probability via mint authority, freeze authority, mutable metadata, and holder concentration. It explicitly distinguishes this security assessment from inspect_solana_token_liquidity, which handles symbol, decimals, and DEX liquidity metadata.

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

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

It gives a clear when-to-use condition: pre-trade security decisions on whether a Solana SPL token is safe to buy. It also names the alternative tool and the exact condition for using that sibling instead, leaving little room for misselection.

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

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

Annotations already declare readOnly/idempotent/non-destructive, yet the description still adds real behavioral facts: stateless edge call, 32 KB response cap, 60 RPM rate limit, default network, '?demo=true' or x402 payment of 20 sats, and an HTTP 400 failure mode for invalid input. That is well beyond annotation coverage.

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

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

Front-loaded with the payload first and the exclusion routing second, and virtually every clause carries operational information. It is somewhat dense with parentheticals crammed into a single long sentence, which slightly hurts scannability.

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

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

For a two-parameter read tool with an output schema, everything an agent needs to call it correctly is present: scope, alternative, auth/payment path, rate and size limits, and error behavior. Return-value details are correctly delegated to the output schema.

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

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

Schema coverage is 100% and both parameters (base58 mint, network enum with default) are already fully documented in the schema. The description only restates that 'mint' is accepted and that 'network' defaults to mainnet-beta, adding no new semantics.

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

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

Names a specific verb and resource set ('Retrieves canonical Solana SPL token metadata including name, ticker symbol, decimal precision, and mint/freeze authority addresses') and explicitly contrasts with the sibling evaluate_solana_token_risk. An agent can distinguish the two without opening a schema.

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

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

Gives an explicit when-to-use ('resolving SPL token decimals, ticker symbols, and registry metadata for portfolio or swap formatting') and a named alternative with its own condition ('for computing a composite security risk score and binary should_transact verdict, use evaluate_solana_token_risk instead').

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world behavior, so the safety bar is met structurally. The description adds genuinely useful context the annotations do not encode: stateless execution, a 32 KB payload cap, 60 RPM throttling, demo/L402 payment options, and an HTTP 400 on invalid input. However it omits what the recommendation output contains and how weight is derived, so it is solid but not exhaustive.

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

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

Purpose is front-loaded in the first sentence, followed by the when-to-use/alternative routing and then operational constraints. Dense but nearly every clause carries information; the packing of rate limit, auth, and error behavior into one parenthetical sentence is slightly crowded but not wasteful.

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

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

With only two simple parameters, full schema coverage, and an output schema, the description need not explain return values. It covers the remaining agent-critical unknowns: statelessness, payload cap, rate limit, payment/auth path, and failure behavior on invalid input.

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

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

Schema description coverage is 100%: both utxos_sats_json (JSON array or comma-separated satoshi values) and script_type (enum with default) are fully documented in the schema. The description restates the script_type default rather than adding new meaning such as accepted value ranges or size limits per UTXO. Baseline 3 applies when the schema carries the load.

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

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

States a specific verb (analyzes) and resource (Bitcoin UTXO satoshi values) plus the three concrete outputs: vByte weight, dust identification, and a consolidate/hold recommendation. It explicitly distinguishes itself from the sibling estimate_bitcoin_mempool_fees, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use condition ('optimizing on-chain Bitcoin treasury UTXO sets to minimize long-term miner fee drag') and names the alternative plus the exact condition that selects it ('for fetching current live Bitcoin mempool sat/vB feerates alone, use estimate_bitcoin_mempool_fees instead'). Nothing is left to inference.

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

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

Annotations already cover read-only/idempotent/non-destructive/closed-world, and the description adds genuinely new operational context: a 32 KB input ceiling, 60 RPM rate limit, demo-mode and L402 pricing (30 sats), and an HTTP 400 failure mode for invalid input. The only gap is that it doesn't explain what the scan report contains, though an output schema exists to carry that.

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

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

Two sentences, front-loaded with the capability and the exclusion, then a dense operational footer. Every clause carries information, though the trailing parenthetical packing limits, pricing, and error codes into one run-on is slightly compressed compared with the clean opening.

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

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

For a read-only two-parameter scanner with a full output schema and complete annotations, the description supplies what structured fields cannot: failure modes, rate/size limits, and payment/auth options. Only the consequence of exceeding the 32 KB limit and the shape of the report are left unstated, and the latter is covered by the output schema.

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

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

Schema description coverage is 100%, so both parameters are already fully documented, including the framework enum and its 'anchor' default — which the description merely restates. It confirms the required input is a source-or-IDL string but adds no syntax, size, or format guidance beyond the schema. Baseline 3 applies when the schema does the heavy lifting.

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

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

States a specific verb and resource ('Scans Solana Anchor and native Rust program instructions') and enumerates the exact bug classes targeted: unverified CPI program IDs, missing signer checks, PDA bump seed canonicalization. It also explicitly distinguishes itself from evaluate_solana_token_risk, so an agent can route between 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.

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

Gives a clear when-to-use ('auditing Solana Rust/Anchor source code or instruction account structs for CPI privilege escalation') and names the alternative with its own trigger condition ('checking live SPL token mint/freeze authorities and rug-pull risk by mint address, use evaluate_solana_token_risk instead'). Both directions of the routing decision are covered.

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

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

Annotations already declare readOnly/destructive/idempotent/openWorld, so the safety profile is covered; the description adds genuinely non-obvious context: statelessness, a 32 KB input cap, 60 RPM rate limit, query-param demo mode or L402 payment (20 sats), and HTTP 400 on invalid input. It does not describe what the decoded output contains, but that is largely covered by the output schema.

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

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

A single dense passage that front-loads the decoding purpose and risk surface before the usage routing, then the operational constraints. No sentence is filler; even the rate limit and payment note are operationally relevant to calling it correctly.

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

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

With an output schema present, the description need not explain return values, and annotations cover safety. It still supplies limits, error behavior, auth/payment options and network default — everything an agent needs to invoke it successfully.

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

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

Schema coverage is 100%, so both parameters are already documented, and the description mostly restates them ('calldata_hex', network default 'base_mainnet'). The only added meaning is the undocumented '?demo=true' query-parameter/payment path, which is marginal. Baseline 3 is correct when the schema does the heavy lifting.

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

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

States a specific verb and resource — decoding raw EVM hex calldata by 4-byte selector — and names the attack patterns it surfaces (approve/transferFrom, setApprovalForAll, multicall). It also explicitly distinguishes itself from the sibling decode_eip712_permit_signature, so an agent can route between 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.

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

Gives an explicit situation for use ('auditing raw hex transaction data (to, value, data) before broadcasting') and an explicit alternative with the condition that selects it ('for inspecting off-chain EIP-712 JSON typed-data signatures, use decode_eip712_permit_signature instead'). Nothing is left to inference.

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

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

Goes well beyond the readOnly/idempotent annotations: discloses statelessness, a 32 KB size cap, 60 RPM rate limit, '?demo=true' and x402 (50 sats) payment paths, and HTTP 400 on invalid input. This is exactly the operational context annotations cannot carry.

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

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

Front-loads purpose, then usage, then operational constraints; every sentence carries weight. Docked one point because the embedded default-window detail is both wrong and adds noise against the schema.

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

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

Output schema covers return values and annotations cover safety, so the description only needs operational context — which it supplies (rate limit, size, payment, demo). The one gap is the ambiguous/conflicting window default that undercuts otherwise complete guidance.

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

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

Schema coverage is 100%, so baseline would be 3, but the description states window 'defaults to 1h' while the schema says it 'defaults to 24h when omitted' — an active contradiction that could cause wrong-window calls. The description adds no reliable meaning beyond the schema and instead introduces conflicting default info.

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

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

States a specific verb and resource: tracks net accumulation/distribution flows across top Solana whale wallets and flags coordinated insider clusters for an SPL token. It explicitly distinguishes itself from the sibling evaluate_solana_token_risk, so an agent can tell them apart 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.

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

Provides explicit when-to-use (analyzing on-chain smart-money order flow and holder clustering) and a named alternative for a different task (static mint/freeze authority checks → evaluate_solana_token_risk). The routing decision is clear.

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

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

Beyond the readOnly/idempotent/openWorld annotations, the description discloses statelessness, a 32 KB payload ceiling, a 60 RPM rate limit, and that invalid input yields HTTP 400 — operational facts an agent cannot get from structured fields. Annotations already cover the safety profile, so this is pure added value.

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

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

Three dense, well-ordered sentences: purpose, usage/alternative, operational constraints — properly front-loaded with no filler. It is somewhat run-on, and the '?demo=true' / '15 sats' fragment is compressed to the point of obscurity.

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

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

With an output schema handling return values and annotations covering safety, the description still supplies what an agent needs to call correctly: input source (raw WWW-Authenticate header), default protocol, size/rate limits, and error behavior. Nothing material is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description restates the 'protocol_hint' default of L402 which the schema already documents verbatim. The reference to '?demo=true' and 'L402 (15 sats)' is cryptic and maps to no declared parameter, adding ambiguity rather than semantics.

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

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

States specific verbs (decodes, verifies) against a specific resource (inbound HTTP 402 payment challenges) and enumerates the three supported protocol shapes (L402 BOLT11+Macaroon, x402 Solana USDC, MPP Base). It explicitly names the sibling it is not (estimate_bitcoin_mempool_fees), so an agent can route 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.

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

Gives an explicit trigger — 'Use when auditing a 402 challenge header before an autonomous agent pays a Lightning invoice or USDC transfer' — plus a named alternative for the adjacent need. When-to-use and when-to-use-something-else are both present.

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