Solana Pulse: agent safety layer

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

Annotations already cover safety (readOnly, idempotent, non-destructive, open world), and the description adds value beyond them: live on-chain reads rather than cached data, plus pricing/rate-limit behavior (25 free calls/day, then $0.01 USDC via x402). The freshness warning is behaviorally important for a balance tool.

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

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

Front-loads the most important guidance (run before spending) before purpose and parameters, and every sentence carries information. The inline parameter recap duplicates the schema, which is the only real waste; the docs pointer at the end is a reasonable close.

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?

Since there is no output schema, the description should ideally say what a successful read returns (units, e.g. lamports vs SOL) — that is the one gap. Everything else an agent needs (when to call, network default, cost, live-read semantics) is 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 description coverage is 100%, so both parameters are already fully documented, including the .sol-name exclusion and devnet-only guidance. The description largely restates the schema (wallet, network, mainnet default) without adding new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource: "Reads a wallet's SOL balance straight from the chain." The SOL specificity distinguishes it from token-oriented siblings like tokens, token_account, and find_token, so an agent can route correctly 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 ("Run before sending SOL or paying fees") and a strong caution ("Never trust a balance remembered from earlier in a chat"), which is genuine usage guidance. It does not explicitly name sibling alternatives for non-SOL balance checks, so it stops short of a full 5.

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

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

Annotations already cover safety (readOnly/idempotent/non-destructive/openWorld), yet the description adds material context beyond them: the 60-90 second expiry window, what the return payload contains, and a concrete rate-limit/cost model (25 free calls/day, then $0.01 USDC via x402). That is exactly the kind of pricing and lifecycle disclosure the rubric rewards.

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 timing guidance and the returned values, and every sentence carries usable information (expiry, return shape, cost, docs pointer). The 'Inputs: network...' sentence redundantly restates the schema, which is the only real slack.

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?

There is no output schema, so the description carries the burden of describing returns, and it does (fresh blockhash, blocks left, seconds left). Cost, default network, and call timing are all present, leaving nothing essential an agent needs missing.

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

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

Schema description coverage is 100% and the schema's network field already documents the default and devnet/mainnet distinction in detail. The description largely repeats that ('Default "mainnet-beta" (real money)') without adding syntax or meaning beyond the schema, so the baseline 3 applies.

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

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

The description states a specific verb+resource+contents: it returns a fresh blockhash plus blocks-remaining and seconds-remaining before expiry. This is clearly distinguishable from every sibling (balance, fee, check_tx, history, etc.), none of which returns a blockhash. An agent can identify this 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.

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

"Run right before building a transaction you'll sign" gives explicit timing for when to call it. No when-not-to-use guidance or named alternative is provided, but no sibling competes for this purpose, so context is clear though not exhaustive.

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

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

Annotations declare readOnly/idempotent/non-destructive, and the description adds substantial context beyond them: it dry-runs on live mainnet without paying a fee, decodes every step, and returns one of three verdicts with reasons. It also discloses the cost model (25 free calls/day, then $0.02 USDC via x402), which appears nowhere in the structured fields.

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

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

Front-loaded with the purpose and the verdict semantics, then cost, then a docs pointer — a sensible ordering. However the explicit 'Inputs:' section duplicates parameter text already present at 100% coverage, which is avoidable padding in an otherwise dense block.

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

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

With no output schema, the description carries the full burden and does so: it names the verdict outputs and their reasons, the decoded steps, per-wallet balance deltas, network options, cost, and a docs URL. An agent has everything needed to call and interpret the result.

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

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

Schema description coverage is 100%, so the schema already fully documents both parameters. The description's 'Inputs:' block largely restates the schema text ('base64-encoded. Signed or not. Legacy and v0 both work' and the mainnet default) rather than adding new meaning, so the baseline 3 applies.

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

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

States a specific verb and resource with an explicit trigger: 'Run on every transaction before you sign it,' then enumerates what it produces (dry-run on live mainnet, per-wallet SOL/token deltas, OK/REVIEW/BLOCK verdict). This pre-signing simulation role is distinct from sibling diagnostic tools like explain_tx or why_failed, which operate post-hoc.

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

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

Gives clear context ('run on every transaction before you sign it,' 'before you pay a fee') and network guidance ('Use devnet only for test wallets'). It does not explicitly name or exclude alternatives such as explain_tx or tx_matches, so it stops short of full when/when-not routing.

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

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

Annotations already declare readOnly/idempotent/non-destructive, and the description adds genuinely new behavioral context: a rate limit and price model (25 free calls/day, then $0.01 USDC per call via x402), which network is read by default ('mainnet-beta (real money)'), and the concrete consequence of misuse. None of that is derivable from the 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?

Well front-loaded: the safety warning and the decimal-scaling example lead, with inputs and cost trailing. It is efficient for the amount of information conveyed, though the Inputs block duplicates schema text and the trailing full-docs URL is marginal.

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

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

No output schema exists, and the description only implicitly conveys the return value via the '5 turns into 5000000' example rather than stating the shape explicitly. Everything else an agent needs — direction, defaults, network selection, quota/cost — is present for a 4-parameter read-only tool.

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

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

Schema description coverage is 100%, so the baseline is 3. The Inputs section largely restates the schema descriptions, and it omits the two enum aliases the schema accepts ('to_base_units', 'to_ui'), so it adds no meaning beyond what the schema already provides.

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

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

States a specific verb and resource: converts between normal token amounts and raw on-chain units using the token's real decimals. It also distinguishes itself from the sibling set by pointing at find_token as the source of the token identifier, so an agent can tell this apart from balance/tokens lookups.

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

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

The first sentence gives an explicit trigger condition ('Run before putting any token amount into a transaction'), and the 'to' guidance pins each branch to a situation: 'raw' before building a transaction, 'readable' when reading raw amounts. The failure mode (1,000x too much or too little from wrong decimals) makes the when-not implicit but vivid.

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 readOnly/idempotent/openWorld, and the description adds real behavioral context on top: the cost model (25 free calls/day, then $0.01 USDC per call via x402), the 'mainnet-beta (real money)' default, and a failure-mode promise (names the failing program and the fix). This is substantive disclosure beyond structured fields.

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

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

Front-loaded with the primary use case and what it returns, with cost and docs citation at the end. Dense and mostly waste-free, though the output enumeration slightly restates the purpose sentence and the pricing sentence is long.

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

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

With no output schema, the description carries the return-value burden and does so: it lists result, fee, balance deltas, programs, and failure cause, plus cost, default network, and a docs pointer. 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.

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

Schema coverage is 100%, so the schema already documents both params fully (including 'never make one up' and devnet guidance). The description restates tx_id and network with a slight nuance ('real money'), which adds marginal value over the schema. Baseline 3 is appropriate.

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

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

States a specific verb and resource ('reads a confirmed transaction and returns...') and enumerates the actual outputs: success status, fee, per-wallet SOL/token balance changes, programs used, and failure reason. It is clear and detailed, but it never names the overlapping siblings (why_failed, check_tx) it must be distinguished from.

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 triggering context: 'Run after a transaction lands (or fails) to report what really happened, instead of guessing from logs.' That contrasts it with ad-hoc log reading, but provides no explicit when-not-to-use or sibling routing (e.g., why_failed for a failure-only lookup).

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 safety (readOnly, idempotent, non-destructive, openWorld), and the description layers on costly, non-obvious traits: a dry run measures compute for the passed tx, 25 free calls/day then $0.01 USDC via x402, and the exact unit returned (micro-lamports per compute unit). These are behavioral facts an agent cannot infer from annotations.

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

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

Front-loaded with the usage instruction and unit-safety benefit, then outputs, then inputs, then cost. Slightly long and partly duplicates the schema's param text, but every sentence carries actionable 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?

Despite having no output schema, the description explains the return shape (three price tiers, compute limit, exact SOL cost per price) and the cost model. Nothing essential to correct invocation 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 params are already fully documented with examples (base64 serialization, enum networks). The description restates the same tx/network semantics without adding format or constraint detail beyond the schema, so the baseline 3 applies.

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

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

States a specific verb and resource: it reads recent on-chain priority fees and returns cheap/normal/fast prices plus compute cost. Clearly distinguishable from siblings like balance, blockhash, or convert.

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?

"Run before setting a priority fee" gives explicit timing/context for use, and the pricing note implies call budgeting. It does not name alternative sibling tools or state when NOT to use it, but the trigger condition is clear.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, openWorld), and the description adds context annotations cannot: the cost model (25 free calls/day, then $0.01 USDC via x402) and the disambiguation behavior (ranking by verification and liquidity, copycat warnings). That is exactly the extra behavioral context the structured fields lack.

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 usage directive, then purpose, then inputs, cost, and a docs pointer — logical ordering with little waste. The usage sentence and the purpose sentence overlap somewhat on the copycat rationale, costing it a point.

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

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

With no output schema, the description carries the return-value burden and does describe the outcome (real token address, ranked matches, copycat warning) plus cost. It stops short of specifying the response shape or how many candidates are returned, which is a minor remaining gap for a resolver tool.

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

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

Schema coverage is 100% and the single parameter already documents 'ticker, name or address' with the same BONK/Jupiter/USDC examples. The description's Inputs block and example simply restate the schema, adding no new syntax or format meaning, so the baseline 3 applies.

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

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

States a precise verb+resource: 'Finds the real token address for a ticker or name' and adds the distinguishing behavior (ranks matches by verification/liquidity, warns on copycats). This clearly separates it from siblings like token_safety, tokens, and token_account, which an agent could otherwise confuse with resolver work.

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 ('Run whenever a user names a token by ticker or name') plus a strong when-not directive ('Never pick a token address from memory'), grounded in the reason tickers aren't unique. It stops short of naming alternative siblings (e.g. token_safety for risk checks), so it's clear but not fully routing.

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

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

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description adds materially more: ordering (newest first), result semantics (worked/not plus plain error name), and a concrete cost/payment model (25 free calls/day, then $0.01 USDC per call via x402). The "mainnet-beta (real money)" warning is a genuinely useful operational caveat.

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 opening sentences are well front-loaded and high value, but the "Inputs:" section duplicates a 100%-covered schema nearly verbatim, and the docs pointer plus cost line stretch a definition that could make its point in half the words.

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

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

There is no output schema, and the description compensates by describing what comes back (latest transactions, success status, plain error name). Cost, network risk, and the tx-ID sourcing use case are all covered; only pagination/limit behavior beyond the schema's max=50 and the docs URL's contents are left implicit.

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 wallet, network, and how_many including defaults, enum values, and the "not a .sol name" caveat. The description's Inputs block largely restates this, adding the "real money" framing but no syntax or format detail the schema lacks.

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

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

States a specific verb+resource ("Lists a wallet's latest transactions, newest first") and even describes the return shape (success flag plus plain error name). An agent can distinguish this from siblings like check_tx, why_failed, and explain_tx, which operate on an already-known transaction.

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 triggering condition ("Run to see a wallet's recent activity, or to get a real transaction ID to look into") and an important prohibition ("Never make up a transaction ID; get one here"). It never names specific alternatives such as check_tx or why_failed, so the routing is implied rather than explicit.

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

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

Annotations cover safety (readOnly=true, idempotent, non-destructive), and the description adds context those fields cannot: the x402 cost model (25 free calls/day, then $0.01 USDC per call), a network default carrying real money, and the fact that the tool returns an existence check plus a creation price. This is exactly the behavioral detail that annotations do not supply.

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 imperative 'Run before sending a token to someone' is front-loaded and the rationale is dense with useful facts. It is slightly longer than needed, and the trailing pointer to external docs (GET /api/tools/token_account) plus a repeated field list add minor redundancy, but nothing is filler.

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

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

With no output schema, the description does its share by naming the three result elements: the derived ATA address, whether it exists, and the creation cost. Cost/rate-limit context is also included. What it omits is any shape for the returned data (e.g., field names or units of the price), which for an output-schema-less tool would have closed the remaining gap.

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

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

Schema description coverage is 100%, so the schema already documents all three params, including the mainnet-beta default and the 'not a ticker' note. The description largely restates that same information ('wallet... usually the recipient', 'network... Default mainnet-beta (real money)') rather than adding format or usage nuance, so the baseline 3 is appropriate.

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

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

The description names a specific verb and resource — deriving the recipient's Associated Token Account (ATA) for a wallet+token — and additionally states it checks existence and prices creation. No sibling (wallet, find_token, tokens, balance) does ATA derivation, so an agent can distinguish it immediately. It even explains why the tool exists ('models can't work this address out in their heads').

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

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

Usage is clearly signaled with 'Run before sending a token to someone,' which tells the agent exactly when the tool applies, and it disambiguates the common error of sending to a wallet rather than a token account. It does not, however, name alternatives or when-not conditions explicitly (e.g., pointing at find_token for obtaining the token address, which only appears in the schema).

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

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

Annotations already cover the safety profile (readOnly, idempotent, openWorld), and the description layers on genuinely new traits: results ranked by USD value, unverified/spam tokens flagged, empty accounts excluded by default, and a concrete cost model (25 free calls/day then $0.01 USDC via x402). The x402 pricing is behavior an agent cannot get from 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?

Purpose is front-loaded in the first sentence and the spam-flagging rationale is useful. The four 'Inputs:' sentences largely duplicate schema text that the agent already receives, adding length without new information, but the structure remains scannable.

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

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

With no output schema, the description steps in to describe the return shape (exact amounts, verified flag, USD value where a price exists) and names the token standards covered. Cost, network defaults, and pagination-like limits are all told, so an agent has what it needs to call and interpret it.

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

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

Schema description coverage is 100% and the schema descriptions are actually richer than the prose (e.g. wallet 'Not a .sol name or a ticker', include_empty rationale). The description essentially restates wallet/how_many/include_empty/network without adding format or edge-case meaning beyond the schema.

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

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

States a specific verb and resource — reading which tokens a wallet holds and how much — and immediately disambiguates from siblings like balance by scoping to SPL/Token-2022 holdings rather than native SOL. The mention of USD ranking and spam-token flagging further sharpens what the tool returns.

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

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

The opening 'Run when you need to know which tokens a wallet holds and how much' gives clear triggering context, and the unverified-flagging note implies when it beats a raw balance check. It never explicitly names an alternative sibling (balance, token_account, find_token) or a when-not condition, so routing still requires some 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 read-only/idempotent/non-destructive, so the description only needed incremental context — and it delivers a lot: the x402 cost model (25 free calls/day, then $0.02 USDC per call), the exact verdict vocabulary, and the analytic method (simulating a real holder sale). None of this is recoverable from the 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?

Verdict-first and front-loaded, with the check list and cost/input details following. The long enumeration of checked signals is the bulk, but each item conveys a distinct capability; only the input restatement overlaps the schema and could be trimmed.

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?

There is no output schema, yet the description specifies the return shape (one of three verdicts plus 'the exact reasons') and the grading criteria. Combined with the cost and documentation pointers, an agent has everything needed to call this correctly without further inspection.

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

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

Schema description coverage is 100% and both parameters are already documented there, including the enum values and default. The description's restatement of token and network adds the phrase 'real money' and clarifies input provenance via find_token/tokens, but this is largely duplicative, so the baseline of 3 applies.

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

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

States a specific action (risk-analysis of a token) and a concrete artifact: it returns SAFE, CAUTION or AVOID with reasons. It enumerates the exact checks performed (liquidity pull simulation, creator record, insider networks, mint/freeze authority, Token-2022 traps), which clearly separates it from siblings like find_token or tokens that only resolve addresses.

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

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

Opens with the trigger condition ('Run before buying, accepting or recommending a token') and closes with an explicit exclusion boundary for the network parameter ('Use devnet only for test wallets'). It also points to a fallback doc endpoint, so the agent knows both when to call it and where to go for detail.

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 by disclosing concrete verification behavior (field-by-field comparison, dry-run balance checks, flagging of extra steps) and, importantly, the cost model: 25 free calls/day then $0.02 USDC per call via x402. Rate/cost limits are exactly the kind of operational context annotations cannot convey.

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

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

Front-loads the trigger and the core promise before the mechanics, and the 'Inputs:' list keeps parameters scannable. Reasonably tight, though the parameter recitation partially duplicates the schema rather than adding new 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 tool with no output schema, the description does explain what the agent gets back in substance: which fields are compared and that non-transfer steps are flagged. It does not specify the response shape or failure/mismatch reporting format, which is the main remaining gap.

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

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

Schema description coverage is 100% and the 'Inputs:' block largely restates the schema's own parameter descriptions (token, amount in normal units, to, from default fee payer, network default mainnet-beta). It adds no format or edge-case detail beyond what the schema already documents, so baseline 3 applies.

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

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

States a specific verb and resource — 'Confirms it moves exactly that token, amount and recipient' for a built transfer transaction. The framing ('run right before signing') cleanly separates it from sibling diagnostics like check_tx, explain_tx and why_failed, so an agent can pick it without inspecting other 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?

Gives explicit timing and trigger context: 'Run right before signing a transfer your agent built from a request like "send 5 USDC to X".' That is a clear when-to-use cue. It stops short of naming alternatives (e.g., when to prefer check_tx or explain_tx instead), so no exclusion guidance is provided.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description adds context beyond them: spam tokens are excluded from the total, and there is a concrete cost/rate limit (25 free calls/day, then $0.01 USDC via x402). It does not disclose pagination or how 'top tokens' is bounded, which keeps it from a 5.

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

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

Front-loaded with the trigger condition, then value proposition, then outputs, then inputs and cost in a logical order. Slightly redundant in places ('One call instead of balance + tokens + history' echoed by 'in one answer') and the input list duplicates schema text, but no sentence is wasted overall.

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

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

With no output schema, the description carries the full burden and does so: it enumerates the return payload (SOL balance, top tokens with USD values, estimated total worth, recent activity), the exclusion of spam from the total, the network default and its real-money implication, and the cost model. An agent has everything needed to call and interpret it.

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

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

Schema description coverage is 100%, so both parameters are already documented in structured form; the description largely restates them. It adds only thin extra context ('Default mainnet-beta (real money)', 'Leave it out for mainnet'), which matches the baseline-3 expectation when the schema carries the parameter detail.

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

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

States a specific verb and resource ('what a wallet holds or is worth') and immediately scopes it against named siblings: 'One call instead of balance + tokens + history.' An agent can distinguish this aggregate view from the granular sibling tools without opening any schema.

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

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

Gives an explicit trigger ('Run when asked what a wallet holds or is worth') and names the alternatives it replaces (balance + tokens + history), plus a qualifier that spam is excluded from the total. Nothing about when to prefer it over the granular tools 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/openWorld/non-destructive, and the description goes well beyond them: it discloses the pricing model (25 free calls/day, then $0.01 USDC via x402), the real-money consequence of misuse, and the scope of returned address classifications. That is exactly the supplementary behavioral context an agent needs before committing 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.

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

Front-loaded with the usage cue and risk, then inputs and cost — a logical order with little waste. The '(real money)' note on the default network is repeated verbatim from the schema, a minor redundancy, but overall it is tight for the amount of information conveyed.

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

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

With no output schema, the description compensates by describing what comes back (address classification plus per-type key facts). Combined with inputs, cost, and the pre-call safety warning, nothing an agent needs to invoke this correctly is missing.

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

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

Schema description coverage is 100% and both parameters are documented, so the schema already carries the load. The description largely restates the schema ('address: Any Solana address', 'network (optional): Which Solana network... default mainnet-beta') without adding format or syntax detail beyond it, so the baseline 3 applies.

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

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

States a specific verb and resource — 'Says what any address is' — and enumerates the outputs (wallet, token account, token, program, stake account) with 'key facts for each'. This clearly distinguishes it from siblings like find_token, token_account, and wallet, which each cover narrower address categories.

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 says when to run it: 'when you're not sure what an address is, before sending to it or passing it to another tool', backed by the concrete consequence that SOL sent to a token or program address can be stuck for good. It doesn't name a specific alternative sibling to use instead, but the trigger condition and preconditions are unambiguous.

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

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

Adds substantial context beyond the annotations: it works offline with no chain call, and carries an explicit cost model (25 free calls/day, then $0.01 USDC via x402). The pricing and offline behavior are exactly the kind of operational detail 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?

Front-loaded with the usage trigger and payoff, then inputs and cost. Mostly tight, though the pricing and docs-pointer sentences add length that slightly dilutes the core signal.

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

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

With no output schema, the description still conveys the return shape ("the plain cause and the fix") and covers inputs, offline behavior, and cost. Nothing an agent needs to invoke it correctly is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters fully. The description largely restates the schema's examples and guidance (error formats, program needed for custom codes) without adding new syntax or format meaning, so the baseline 3 applies.

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

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

States a specific verb+resource (turns a Solana error into the plain cause and the fix) with clear scope, and distinguishes itself from siblings like explain_tx and check_tx by being the error-to-diagnosis tool. An agent can tell what it does 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?

Explicit trigger: "Run whenever a Solana transaction or dry run fails, before retrying," plus a rationale ("retrying without knowing why just burns fees"). It also points to explain_tx as a source for the program argument, giving routing context against siblings.

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