Solana Pulse: agent safety layer

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

Annotations already cover readOnly/idempotent/non-destructive/openWorld, so the safety profile is settled. The description goes further by disclosing the cost model (25 free calls/day, then $0.01 USDC per call via x402) and a freshness discipline ('Never trust a remembered balance'), both of which are real behavioral context beyond 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?

Dense and waste-free: trigger, purpose, example, cost, and output pointer. The ordering is slightly inverted (usage precedes the statement of what the tool is), and the trailing 'Outputs explained: GET /api/tools/balance.' is an odd fragment, but nothing is padded.

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

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

A two-parameter read tool with no nested objects and no output schema is well covered by trigger + purpose + example + cost. The only gap is return shape, which is gestured at via a docs URL rather than described, so an agent knows what to pass but not exactly what comes back.

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 `wallet` and `network` (including the .sol-name exclusion and the devnet warning). The description only adds the inline example {"wallet": "<address>"}, 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: 'A wallet's SOL balance, read from the chain.' The 'SOL' qualifier implicitly separates it from sibling token-balance tools (tokens, token_account, find_token), so an agent can route correctly without opening schemas. No tautology, no vagueness.

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 strong prescriptive trigger ('Run before sending SOL or paying fees, to confirm the wallet has enough. Never trust a remembered balance.'), which is exactly the when-to-use context an agent needs. It lacks an explicit when-not or a named alternative sibling, so it falls just short of the top band.

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, open-world behavior, so the safety profile is covered. The description adds genuinely new context the annotations cannot carry: the ~60-90 second expiry window, the metered cost (25 free calls/day, then $0.01 USDC per call via x402), and where output semantics are documented. The cost/rate-limit disclosure is particularly valuable and would otherwise be invisible.

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 operative instruction and the time-sensitivity constraint are front-loaded in the first two sentences, followed by output expectations and cost. Most sentences earn their place, though 'Example: {}.' is filler that conveys nothing and slightly dilutes the structure.

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 bears the return-value burden and does describe the payload (a fresh blockhash, blocks remaining, approximate seconds remaining). Combined with the cost and expiry context, an agent has enough to call this correctly; the pointer to external docs for 'outputs explained' is a minor reliance on off-tool 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% and the single 'network' parameter already documents its enum, default, and the real-money vs test-wallet distinction. The description says nothing about the network parameter and adds no syntax or default information beyond the schema. Baseline 3 is appropriate when the schema carries the whole 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?

The description states a specific verb+resource: it returns a fresh blockhash plus the blocks and seconds remaining before expiry. That is clearly distinct from every sibling (balance, check_tx, fee, tokens, etc.), none of which deal with blockhashes. It is only slightly muddied by leading with an imperative ('Run just before building a transaction to sign') rather than naming the artifact first.

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 an explicit trigger condition ('Run just before building a transaction to sign') and quantifies the operative constraint ('expire in about 60-90 seconds'), which tells the agent precisely when this call is and isn't worth making. No alternative tool is named, but no sibling performs this function, so there is nothing to route away to.

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 mark it read-only and non-destructive, but the description adds substantial behavioral context: it returns an unsigned transaction with fresh blockhash and priority fee, runs check_tx/tx_matches/token_safety, exposes readiness and reasons, and has free-tier plus per-call pricing.

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 important trigger and safety condition are front-loaded, and every sentence carries useful information. It is dense and semicolon-heavy, 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?

For a complex transaction-building tool with no output schema, the description covers the full behavioral contract: unsigned output, ready_to_sign gating, internal checks, token safety behavior, signing prohibition, and cost. An agent has enough context to invoke and interpret it correctly.

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

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

Schema description coverage is 100%, so the schema already fully documents the nine parameters. The description adds an example call, but otherwise does not add much parameter syntax or format detail beyond what the schema provides.

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

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

The description states a specific verb and resource: it builds a SOL/token transfer or Jupiter swap as an unsigned transaction. It also distinguishes this from sibling tools by saying it runs check_tx, tx_matches, and token_safety internally.

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 trigger: use when an agent needs to send SOL or a token, or swap through Jupiter. It also states the key gating condition: sign only when ready_to_sign is true, and never signs or sends itself.

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, open-world behavior, and the description adds substantial context beyond them: live-mainnet dry-run, verdict semantics with reasons, measured false-positive rate, and a concrete pricing/rate limit (25 free calls/day, then $0.02 USDC via x402). No claim conflicts with the annotations.

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

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

The usage imperative is front-loaded, followed by capability, evidence, example, and cost in a logical order. It is slightly dense with promotional asides ('benchmark/ in the repo', 'Outputs explained: GET /api/tools/check_tx'), but nearly 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?

With no output schema, the description fully covers return behavior by enumerating the OK/REVIEW/BLOCK verdict with reasons. Combined with cost, network scope, and a worked example, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and already documents both parameters thoroughly, so the baseline is 3. The description reinforces the critical semantics with an example showing tx as base64 'before signing', which clarifies the parameter's intended state beyond the schema wording.

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 action and object ('dry-runs' each step, decodes transactions, returns OK/REVIEW/BLOCK verdicts) and frames its unique scope as a pre-signing safety check. That behavior is clearly distinct from siblings like explain_tx, why_failed, and tx_matches, which it complements rather than duplicates.

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 on every transaction before signing' gives an explicit trigger condition, and the mention of tx_matches' 9-of-9 catch rate implies the complement rather than a substitute. It does not explicitly name when to prefer explain_tx or why_failed, so the exclusions are left implicit.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so safety is covered. The description adds genuinely new operational context: rate limits ('25 free calls a day') and a paid fallback ('$0.01 USDC per call (x402)'), which an agent must know before calling in a loop.

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 ('Run before...') and the failure mode before details, then packs example, cost, and doc pointer. Dense but nearly every sentence earns its place; the trailing 'Outputs explained: GET /api/tools/convert' is a bare pointer rather than prose.

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, but the description partially compensates with a concrete output example and a doc pointer for output details. Combined with full schema coverage, an agent has enough to call it correctly, though return-shape specifics remain external.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real interpretive value beyond the schema: a worked example ('{"token": "SOL", "amount": "0.5"} gives 500000000') and the concrete 5 USDC = 5,000,000 raw units mapping that clarifies the raw/readable direction.

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 amounts and raw units with the token's real on-chain decimals') and frames the concrete risk it addresses ('wrong decimals send 1,000x too much or too little'). An agent can distinguish this from siblings like find_token or balance 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: 'Run before putting any token amount in a transaction,' plus direction guidance implying readable mode for chain-read amounts. It doesn't name an alternative tool or state when NOT to use it, but the triggering context is unambiguous.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive, openWorld), and the description adds real value on top: it confirms it reads a confirmed transaction and discloses cost/rate limits ('25 free calls a day, then $0.01 USDC per call (x402)'). That pricing detail is exactly the kind of context an agent needs and 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 key trigger and purpose, then adds outputs, an example, cost, and a doc pointer. Mostly efficient, though 'For failures it names the failing program and the fix' and 'why it failed' are somewhat redundant.

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

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

For a read-only tool with fully documented params and no output schema, the definition covers purpose, trigger, return contents, cost, and a doc link. It is essentially complete, with only the sibling-relationship gap as a minor shortfall.

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 tx_id and network thoroughly (including the enum and 'never make one up'). The description only restates this with an example, adding little beyond what the schema provides, 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?

States a specific verb+resource: it explains a confirmed transaction, reporting outcome, fee, SOL/token changes, programs used, and failure reason. This is clearly distinguishable from generic readers, but it never names siblings like check_tx or why_failed, whose purpose appears to overlap with the 'why it failed' part.

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 after a transaction lands or fails... instead of guessing from logs.' That establishes when to reach for it. It stops short of stating when-not to use it or naming an alternative such as check_tx or why_failed.

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, open-world, so the bar is lower — yet the description adds real context: exact pricing (25 free calls/day, then $0.01 USDC per call via x402), the unit-conversion guarantee, and a dry-run implication when a tx is supplied. It also points to where outputs are explained, which preempts the missing 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?

Front-loaded with the trigger, then the payoff, then usage modes and cost. Dense but each sentence carries signal; the trailing 'Outputs explained: GET /api/tools/fee' is slightly awkward as prose but still informative.

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?

Two optional parameters, no output schema, and the description covers return shape (three price tiers, units, SOL total), cost/rate limits, and the optional-tx behavior. Nothing an agent needs in order to call it correctly is missing.

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

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 earns above that by explaining the zero-argument mode ({} returns network-wide prices) and by clarifying that supplying tx yields the compute limit plus exact cost at each tier — the 'why' behind the parameter, not just its format.

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

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

States a concrete verb and resource: it computes a Solana priority fee, returning three tiers (cheap/normal/fast) plus compute-limit-aware costs. The unit detail ('micro-lamports per compute unit' and total in SOL) makes it unmistakable versus siblings like convert or balance.

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 an explicit trigger, and the description distinguishes the two invocation modes ({} for network prices vs {"tx": ...} for your own transaction). It does not name sibling alternatives or say when another tool would be preferable, which keeps it out of 5 territory.

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 substantial behavior the annotations cannot convey: ranked-by-verification-and-liquidity results, copycat warnings, the x402 cost model with 25 free calls/day then $0.01 USDC per call, and a pointer to the output documentation. Rate/cost disclosure is exactly the kind of context annotations miss.

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 and packs cost, ranking, and warning behavior into a short block. The trailing 'Outputs explained: GET /api/tools/find_token' is a slightly awkward fragment, and the embedded JSON example is marginally redundant, but overall no wasted sentences.

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

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

For a one-parameter, read-only lookup with no output schema, the description covers trigger, parameters, ranking semantics, edge cases (copycats), cost, and even points to where outputs are documented. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100% and the schema already documents the 'name' parameter thoroughly, including the 'exactly as the user wrote it' guidance. The inline example {"name": "BONK"} restates what the schema already shows rather than adding new semantics, 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?

States a specific verb and resource ('finds the real address for a ticker or name'), plus the ranking behavior and copycat warning. This is clearly distinguishable from siblings like token_safety, tokens, and balance, which an agent can tell apart 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?

Explicit trigger ('Run whenever a user names a token'), an explicit anti-pattern ('Never take an address from memory'), and the reason copycats make this necessary. The agent knows exactly when to reach for this tool and why shortcuts are dangerous.

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 mark this read-only, idempotent and non-destructive; the description adds genuinely new context: newest-first ordering, per-transaction success status, plain-name error reporting, and a concrete cost model (25 free calls/day, then $0.01 USDC per call via x402). Pagination behavior is left entirely to the `before` schema field and the return payload is deferred to an external URL rather than described.

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 lead sentence is well front-loaded, but the second and third sentences overlap ("recent activity" vs. "latest transactions") and the trailing "Outputs explained: GET /api/tools/history" is a cryptic endpoint reference of questionable value to an agent. Editing would tighten it without losing 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 4-parameter read tool with full schema coverage and no output schema, the description covers purpose, ordering, success/error reporting, and cost, which is enough to call it correctly. The one real gap is what the next-page cursor looks like on return, which is only hinted at in the 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 every parameter including `before`, `network` and `how_many` is already documented in structured fields. The description only restates this via an example payload ({"wallet": "<address>", "how_many": 5}), which aids invocation but adds no semantics beyond the schema. Baseline 3 is appropriate.

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

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

States a concrete verb and resource: it "lists a wallet's latest transactions, newest first," and adds that it can also surface a real transaction ID. It implicitly steers the agent away from fabricating IDs for downstream tools, but it never names a specific sibling like check_tx or explain_tx to draw the boundary crisply.

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 to see a wallet's recent activity or get a real transaction ID. Never make one up" gives a clear triggering condition and an important prohibition on invented IDs. It does not spell out when to prefer this over check_tx, explain_tx, or tx_matches, so the exclusion is only implied.

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, openWorld), so the bar is lower. The description still adds valuable non-schema behavior: it says it reports existence and prices account creation, and discloses the paywall (25 free calls/day then $0.01 USDC via x402) — a real constraint the agent cannot see in 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?

Dense but front-loaded: the imperative 'Run before sending a token' and the ATA explanation come first, then example, then cost. The trailing 'Outputs explained: GET /api/tools/token_account' is slightly awkward and reads like a docs pointer rather than a sentence, but nothing is wasted.

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

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

There is no output schema, and the description compensates by stating what the call reports (existence and creation cost), plus the routing rationale and pricing. It points to an external endpoint for output details instead of describing return shape inline, which is a minor gap for a read tool with no 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%, so the baseline would be 3. The description earns above baseline by reinforcing the non-obvious semantic that wallet is the owner/recipient and token must be an address rather than a ticker, plus a worked example showing a USDC lookup end to end.

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: 'Finds the token account (ATA) for a wallet and token with the token's real program, says if it exists, and prices creating it.' It also distinguishes itself from siblings by naming find_token and tokens as the source of the token address, so an agent knows where token_account sits in the flow.

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

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

Gives explicit when-to-use guidance ('Run before sending a token') and explains the underlying reason tokens go to an ATA, not the wallet. It stops short of naming when NOT to use it or listing a sibling alternative for the same job, but the trigger condition is unambiguous.

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

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

Annotations already cover readOnly/idempotent/openWorld, but the description adds genuinely non-obvious behavior: spam/unverified airdrops are flagged so the agent doesn't report fake holdings, results are USD-ranked, and there is a metered cost (25 free calls/day then $0.01 USDC via x402). It stops short of pagination or rate-limit 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?

Front-loaded with the core purpose and mostly efficient, but the opening 'learn which tokens a wallet holds and how much' is immediately restated in the third sentence about listing tokens with amounts and values — one sentence of redundancy in an otherwise tight 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?

No output schema exists, so the description must carry return-value context; it names the returned fields (amount, verified, USD value) and points to an external explanation page. That covers the essentials, though it doesn't fully describe the response shape or headline values.

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 every parameter (wallet, network, how_many, include_empty) is already well documented in the schema. The description's example ({"wallet": ..., "how_many": 10}) restates rather than adds meaning, so this sits at the baseline 3.

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

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

States a concrete verb+resource ('lists a wallet's tokens') and pins down scope: SPL Token and Token-2022, exact amounts, verification status, USD value, ranked highest-value-first. That is enough to distinguish it from balance, token_account, find_token, and token_safety 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?

Usage is implied by 'Run to learn which tokens a wallet holds and how much,' and it hints at when to set include_empty ('only to find empty accounts, e.g. to close them'), but it never names an alternative sibling or states when NOT to use this tool (e.g. for a single token's safety, use token_safety). No explicit routing guidance.

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

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

Goes well past the readOnly/idempotent annotations by disclosing cost mechanics (25 free calls/day, then $0.02 USDC via x402), the simulation behavior (a real holder sell to test liquidity pull), and the exact verdict/rug_chance output shape. For a paid, open-world external call, these are precisely the traits an agent needs before invoking.

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

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

Front-loaded with the trigger and the output vocabulary, then evidence, then an example, then cost — a sensible priority order with little redundancy. The trailing "Outputs explained: GET /api/tools/token_safety" is cryptic (a URL fragment rather than a sentence) and the middle clause listing checks is dense, but nothing is wasted.

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

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

With no output schema, the description still names the verdict enum, the rug_chance semantics (high with reasons, or null), and the cost model, which is enough to decide and call. The full output payload is deferred to an external docs path, leaving the agent to infer field-level detail.

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, including the mainnet-beta vs devnet distinction. The description adds a worked example showing the token address format, but says nothing about the network parameter or what an invalid/unknown token returns — marginal lift over 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 action (safety-check a token) and a concrete, enumerated return (SAFE / CAUTION / AVOID plus rug_chance), and lists the exact signals checked (liquidity pull, creator record, insider wallets, mint/freeze powers, Token-2022 traps). This is unmistakably distinct from siblings like find_token or tokens, which 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?

"Run before buying, accepting or recommending a token" gives a clear triggering condition, and the parameter description routes the agent to find_token/tokens first to obtain the address. It stops short of naming a when-not case or an alternative verdict tool, but the usage context is unambiguous.

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

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

Annotations already cover read-only, non-destructive, idempotent, open-world behavior, so the bar is lower. The description still adds valuable beyond-schema context: pricing (25 free calls/day then $0.02 USDC via x402) and a pointer to output docs. It stops short of 5 by not detailing rate-limit failure modes or result size beyond the paging param.

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 conditions and then the mechanics, which is good ordering. There is minor redundancy between 'follows the money' and 'Follows a wallet's money through its recent transactions', but overall it is dense with little waste.

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, but the description compensates with a concrete example, pricing, and a pointer to the output documentation, plus an explicit enumeration of what is returned. Enough for an agent to invoke correctly, though the output-docs pointer is off-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 schema already documents all five parameters including the paging cursor and time zone. The description only adds a sample invocation ({wallet, how_many}) and does not deepen parameter meaning, which is the correct baseline expectation.

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 — follows a wallet's money through its recent transactions — and lists distinguishing outputs (net SOL/token change, counterparties, where most money went, drain patterns with evidence). This clearly separates it from generic siblings like history or wallet.

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 triggering conditions: 'when a wallet was drained or money went missing, or before trusting an address someone gave you.' It does not name an alternative sibling (e.g. why use this over history or token_safety), so it stops short of 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 the safety profile, and the description adds real beyond-schema context: cost (25 free calls/day then $0.02 via x402), dry-run balance checking, step flagging, and accuracy stats on 200 mainnet transactions. This is exactly the kind of operational detail the annotations don't 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?

It is front-loaded with the trigger ('Run just before signing'), but the middle is dense and repetitive (re-explaining amount/recipient matching several times) and packs in benchmark stats plus a cost/URL line. Every element is defensible, but the result is longer than needed and could be tightened.

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 verify-before-signing tool with no output schema, the description covers inputs, semantics, cost and the kinds of findings returned, and points to a docs URL for output format. The return shape itself isn't concretely specified, keeping it from a 5.

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

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

Schema coverage is 100%, so parameters are already documented; the description still adds value with a concrete worked example and the critical guidance 'Never take [to/from] the transaction' for expected.to. The distinction between transfer and swap field sets is conveyed, though partly by the schema itself.

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 (verify a transfer/swap transaction matches the user's request before signing) with a precisely defined resource and scope. An agent can distinguish it from siblings like check_tx, explain_tx and why_failed because the description frames it as intent-matching against an 'expected' spec.

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 just before signing a transfer... or a swap' gives an explicit timing/trigger condition and the failure modes it protects against. It does not explicitly name sibling alternatives or when-not-to-use, so it falls short of a 5.

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

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

Beyond the annotations (readOnly, idempotent, non-destructive), the description discloses the pricing/authorization model: 25 free calls per day, then $0.01 USDC per call via x402. That is the kind of thing an agent cannot get from structured fields and needs before calling.

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

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

Front-loads the trigger condition, then the result, then examples and cost — a sensible ordering with little waste. The closing 'Outputs explained: GET /api/tools/tx_version' is a slightly awkward pointer but short.

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 tells the agent what the answer contains (version classification and compatible readers) and notes cost/auth. Minor gap: it defers output detail to an external URL instead of stating the response shape, and doesn't explain network-specific differences.

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 adds call-shape examples showing the tx vs tx_id alternatives in concrete form. It adds modest value over the schema's existing 'Give this or tx_id' wording rather than deep 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 a specific verb and resource: it reports whether a transaction is legacy, version 0, or version 1, and which readers can decode it. That is easily separable from siblings like check_tx, explain_tx, and why_failed, which diagnose status rather than transaction format/version compatibility.

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 triggering conditions: when code can't find or read an on-chain transaction, or before relying on code that reads other people's transactions. It doesn't name a sibling alternative directly, so the exclusion boundary is inferred rather than stated.

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

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

Annotations already declare read-only, idempotent, open-world, non-destructive, so safety is covered. The description adds genuinely new behavioral facts: spam tokens are excluded from the total, the call is a paid x402 endpoint with a free-tier quota, and it aggregates four result categories into one answer.

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 trigger condition is front-loaded in the first sentence, followed by the differentiator, the payload summary, an example, and pricing. Every sentence carries distinct information with 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?

No output schema exists, but the description enumerates what comes back (SOL balance, top tokens with USD values, estimated total, recent activity) and points to the documented output spec, so an agent knows both how to call it and roughly what to expect. Nothing material is missing for a 2-param read tool.

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

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

Schema coverage is 100%, so both params are already documented, giving a baseline of 3. The description adds an inline invocation example ({"wallet": "<address>"}) that shows the call shape, but says nothing about the network enum's mainnet/devnet tradeoff beyond what the schema already states.

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 ('what a wallet holds or is worth') and explicitly positions itself against siblings: 'One call instead of balance + tokens + history.' An agent can distinguish it from balance, tokens, and history without opening any schema.

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

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 three sibling tools it replaces, which is exactly the routing decision an agent faces. Cost/rate-limit context (25 free calls/day, then $0.01 USDC via x402) further informs when to prefer this over multiple cheaper calls.

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 goes well beyond them by disclosing cost and throttling ('25 free calls a day, then $0.01 USDC per call (x402)') plus the real-world consequence of misuse. This is exactly the contextual layer 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-loads the trigger condition and the risk of misuse before capability, example and cost. Dense but every clause carries weight; the trailing 'Outputs explained: GET /api/tools/whats_this' is the weakest element, reading more like a doc link than guidance.

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 shape of the return ('what any address is... with its key facts') and points to an explanation endpoint for the rest. That is adequate for a single-address lookup, though the returned fields themselves are never enumerated.

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 the address and network parameters (including the mainnet-beta default and devnet caveat) are already fully documented in the schema. The description's USDC example illustrates what the address might be rather than adding format or syntax detail, so the schema remains the primary source.

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 broad resource: identifies what any address is ('wallet, token account, token, program, stake account and more') with key facts. It implicitly subsumes single-purpose siblings like wallet, find_token and token_account, but never names them, so the agent must infer the routing decision itself.

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

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

Gives a clear triggering condition ('run when unsure what an address is, before sending to it or passing it on') and a concrete consequence that motivates it (SOL sent to a token or program address can be lost for good). Strong when-to-use, but no explicit when-not-to-use or named alternative tools.

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 openWorld. The description adds genuine extra context beyond them: it runs offline with no chain call, and discloses the cost model (25 free calls/day, then $0.01 USDC per call via x402). It does not describe the return shape, but the cost and offline behavior are material facts.

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 and the value proposition, followed by cost and a concrete example. Dense but every sentence carries signal, aside from the slightly cryptic closing "Outputs explained: GET /api/tools/why_failed."

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 reasonably by explaining it maps errors to a cause and fix, discloses cost and offline behavior, and gives a worked example. It is complete enough to call correctly, though the return format remains unspecified.

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 in the schema. The inline example (error 0x1771 plus the JUP6 program address) illustrates the expected shape, which is marginally helpful, but the description adds little beyond what the schema provides. 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: it turns a Solana error (hex code, log line or RPC error) into the plain cause and fix. This clearly distinguishes it from siblings like explain_tx or check_tx, which analyze transactions rather than diagnose error codes.

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 whenever a Solana transaction or dry run fails, before retrying" gives an explicit trigger condition and timing (before retry). It does not name a specific alternative tool, so it falls short of full when-not/alternatives guidance.

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