PumpView — Solana Trading & Live Data

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

Goes well beyond the annotations: auth requirement (Bearer key + linked wallet), cost model (0.5% + tips + network fees), what is returned, timeout/retry behavior, and the meaning of 409 vs 410. The annotations only flag non-read-only/idempotent, so this extra context is genuinely additive.

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

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

Front-loaded with purpose and then proceeds through prerequisites, costs, output, and error handling in a logical order; each sentence carries operational weight. It is dense and run-on in places, which costs a little readability.

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

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

For an 8-parameter mutation tool with an output schema, the description still covers auth, funding requirements, cost breakdown, retry/idempotency, and error semantics — everything needed to invoke and follow up correctly. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already explains every parameter thoroughly; baseline is 3. The description reinforces request_id persistence/409 coupling and the slippage policy, but adds little parameter syntax or meaning not already in the schema fields.

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 ('build and simulate an unsigned ExactIn swap') plus scope ('without spending funds'), and names the sibling (submit_swap) that completes the workflow. An agent can immediately distinguish it from get_swap_status and submit_swap.

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 sequencing: check get_trading_config first, then build, sign locally, and call submit_swap. Adds concrete exclusion conditions (no data subscription/credits needed, min $5 unless Unlimited) and error-code routing for 409/410 plus the 'never silently increase slippage' rule.

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

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

With annotations only covering readOnly/idempotent/destructive/openWorld, the description adds substantial behavioral context the annotations do not: bearer-key auth requirement, zero data-credit consumption, reads Solana at finalized with specific validation fields, and the explicit assurance it never broadcasts. It also maps 400/404/409/503 to concrete meanings.

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 purpose is front-loaded and no sentence is filler — error codes, idempotency, and next-step routing all carry operational value. Slightly dense as a single run-on block with irregular indentation, but every clause earns its place.

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

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

For a confirmation call with an output schema, the description still supplies everything an agent needs: auth, side effects (activates package, no credits), idempotency behavior, the full error taxonomy, and the follow-up tool sequence. Nothing material is missing.

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

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

Schema description coverage is 100%, so the schema already documents signature (base58, not a login signature/private key) and invoice_id (from get_payment_instructions, not a swap id). The description adds no parameter-level 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+resource ('Verify an already-broadcast invoice payment and activate the purchased data package') and explicitly scopes it to payments already broadcast, which cleanly separates it from prepare_invoice_payment and get_invoice_status. An agent can pick this without opening a sibling schema.

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

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

Gives explicit preconditions (payment must already be broadcast, bearer key for the invoice owner), post-success routing ('use get_access_status, then get_recent_trades or get_stream_connection'), and retry guidance tied to a specific status ('409 ... retry this confirmation with backoff, not the payment'). Alternatives and exclusions are named rather than 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?

Goes well beyond the readOnly/idempotent annotations by disclosing auth requirements ('Bearer key required'), cost behavior ('no data credits consumed'), return semantics ('remaining=-1 means Unlimited', 'empty grants list means no unexpired package', a grant can still have zero credits), and an explicit scope exclusion (key-specific budgets are dashboard-managed and not in this response).

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 purpose, follows with the trigger condition, then the return contract, then sibling routing. Every sentence carries information an agent needs; 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?

With an output schema present, the description needn't restate return shapes, yet it still adds the interpretive details (unlimited sentinel, empty-list meaning, excluded budgets) that make the response usable. Complete for a no-arg status tool.

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

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

The tool takes zero parameters, so the baseline is 4; there are no parameter semantics to add, and the description correctly does not invent any.

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 ('Inspect') and resource ('the authenticated account's live-data grants, rate limit and feed health'), itemizing the three artifacts returned. An agent can distinguish it from sibling status tools like get_swap_status or get_trading_usage 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?

Explicitly says when to call ('before consuming data or after an access error') and routes to three named alternatives with their respective domains (get_trading_usage for swap volume, get_trading_config for swap policy, get_payment_instructions for invoices). Nothing is left to inference.

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

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

Annotations already declare read-only/idempotent/non-destructive, and the description adds substantial context beyond them: bearer key auth requirement, no data credits consumed, the meaning of paid=false (not settled by PumpView, not proof of no on-chain payment), and the 404 behavior. The paid=false caveat is a genuine semantic nuance an agent could otherwise misread.

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

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

Front-loaded with the core action, and nearly every sentence carries operational value (auth, cost, non-payment warning). Slight deduction because enumerating the returned fields (payer, recipient, amount, memo, expires, paid) partially duplicates the output schema.

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

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

With an output schema present and annotations covering the safety profile, the description supplies exactly the remaining gaps: auth, credit cost, the paid=false interpretation, and the escalation path to confirm_invoice_payment. Nothing needed 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 the schema itself carries the important disambiguation ('Not a swap id or Solana transaction signature') plus a regex pattern and example. The description adds nothing further about invoice_id, so 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 ('Read one of your account's existing invoices') and immediately scopes it against adjacent operations ('without creating or paying another'), which cleanly separates it from prepare_invoice_payment and confirm_invoice_payment. An agent can identify the tool without opening the schema.

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

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

Explicit routing rules are given: if the wallet already broadcast, use confirm_invoice_payment with that signature; do not pay again while waiting. It also names the failure condition (missing or another account's invoice returns 404), so both when-to-use and when-not-to-use are covered.

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

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

Annotations already declare readOnly/idempotent/non-destructive, but the description goes further: it specifies public access with no key or data credits, that it does not create an account, sign, pay, or trade, and that its output includes ordered HTTP wallet-challenge steps. This is meaningful behavioral context beyond the annotations.

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

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

Front-loaded with the core purpose, then permissions, then return content, then sibling routing. Every clause carries information the agent needs; 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?

With an output schema present, return values need not be spelled out, yet the description still summarizes the payload (URLs, challenge steps, workflows) and covers prerequisites, exclusions, and next steps. 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the schema is trivially complete. Baseline 4 applies for a no-parameter tool.

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 (get) and resource (onboarding/API-key setup and integration instructions) and scopes it temporally ('before your first PumpView call'). It is immediately distinguishable from siblings like get_payment_instructions or get_trading_config, which it names.

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 use it (before the first call), when it is safe to use (public, no key or credits), and routes the agent afterward: 'use get_trading_config for swap policy or get_access_status for your purchased access.' Both condition and alternative are named.

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

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

Annotations only declare readOnly=false, idempotent=false, destructive=false; the description adds far more: auth requirements (Bearer key, linked Solana wallet), specific failure codes (409 missing wallet, 404 unknown plan, 503 sales disabled), the returned field set, and the non-idempotent warning to retain the invoice ID rather than retry blindly — which directly aligns with idempotentHint=false. No contradiction with 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 purpose, then preconditions, error codes, return shape, and the payment lifecycle; nearly every sentence carries unique operational value. It is long for a one-parameter tool, but the density is justified rather than 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?

Despite an output schema being present, the description still sketches the return values (invoice id, payer, recipient, mint, atomic amount, memo, expiry) and covers auth, error states, idempotency risk, and the full downstream workflow. 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 description coverage is 100% and the single 'plan' parameter is already documented in the schema with valid ids and a display-name caveat. The description reinforces that a current plan must be chosen first but adds no 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?

Opens with a specific verb+resource: 'Create a new unpaid USDC invoice for a live-data package', plus the reassurance 'this spends no funds'. It goes further than most by naming several siblings it is not (submit_swap is for swaps, prepare_invoice_payment is the next step), so an agent can place it precisely in the workflow.

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 preconditions ('Call only after choosing a current plan with list_data_plans and checking get_access_status'), an exclusion ('Trading alone needs no data subscription'), and the ordered follow-up chain (prepare_invoice_payment -> sign/broadcast -> confirm_invoice_payment). This is textbook when/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.

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

Goes far beyond the annotations: auth requirements (Bearer key, active data grant, sufficient budget), a precise cost formula (max(1, returned event count) credits, repeated reads billed), package-cap behavior, feed ordering, and per-status-code recovery instructions for 409/402/503 including the 'restart without after and record a gap' action. The credit-charging detail also substantiates the non-idempotent annotation.

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 clause, then alternatives, then operational constraints. The dense error-code and credit sentences are load-bearing rather than filler, though the block reads as a wall of prose that could be tightened with list 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?

An output schema exists so return shape needn't be spelled out, yet the description still names the returned cursor and health, which are the fields an agent must act on. Auth, budget, pagination, error recovery, and stream alternative are all covered for a 4-param open-world 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 the baseline is 3, but the description adds genuinely non-schema semantics: filtering happens after batch scanning, so an empty batch still requires advancing with the returned cursor, and a 409 requires retrying without 'after'. That clarifies how after/limit/mint/wallet interact rather than restating them.

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

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

States a specific verb and resource ('Read filtered market swap summaries from PumpView's supported SOL-pair feed') with clear scope, and immediately distinguishes itself from the closest sibling by naming get_swap_status as the receipt tool. An agent can tell this apart from get_stream_connection and get_swap_status 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 when-to-use ('recent market activity'), explicit when-not ('not your submitted swap receipt'), and names two alternatives with their selecting conditions: get_swap_status for receipts and get_stream_connection for continuous WSS delivery. Nothing is left to inference.

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

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

Annotations declare read-only/idempotent/no-destruction, and the description still adds substantial operational context beyond them: this lookup consumes no data credits and opens no connection, the runtime must connect and supply its own key, only one concurrent WSS connection exists per account, delivered events do bill credits, and cursors must be persisted with defined expiry behavior. This is exactly the kind of disclosure annotations cannot carry.

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

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

Front-loaded with purpose and the polling alternative, then packed with operational constraints. Every sentence carries new information, though the single dense paragraph could be broken into bullets for scanability.

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?

An output schema exists, so return values need not be explained, yet the description still notes the shape (url, Authorization header template, first_message, cursor-resume steps). Auth requirements, credit implications, concurrency limits, and cursor lifecycle are fully covered for a streaming-setup tool.

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

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

The tool takes zero parameters with 100% schema coverage, so there is nothing parametric to document; baseline for a no-parameter tool applies. The description correctly does not invent parameter guidance.

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 ('Get WSS setup for continuous live trades') and immediately contrasts it with the polling alternative get_recent_trades. An agent can distinguish this from every other sibling 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?

Explicitly says to use this 'instead of polling get_recent_trades', names the prerequisite (Bearer key with an active eligible data grant/budget), and gives the failure signal (402 = access unavailable). When-to-use, alternative, and precondition are all present.

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

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

Beyond the readOnly/idempotent annotations, it discloses auth requirements (owning account's Bearer key), cost (no data credits consumed), the status lifecycle, and the caveat that receipts may be null while RPC metadata catches up. It also explicitly bounds behavior: 'never submits, signs or rebuilds a trade' and only refreshes stored status/receipts.

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 each subsequent sentence carries distinct information (auth, cost, return fields, lifecycle, polling, refresh semantics). It is dense but not padded; the only minor cost is length in the middle section.

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 status poller with a full output schema, the description covers everything an agent needs: auth, cost, the meaning of each state, the null-receipt edge case, polling discipline, and the guarantee that no write occurs. Nothing material is missing.

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

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

Schema description coverage is 100% and the swap_id field is already documented as a PumpView id rather than a Solana signature or request_id. The description adds no further parameter-level detail, 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?

The description opens with a specific verb and resource ('Check an existing account swap after submission') and scopes it temporally ('after submission, including after a timeout'). This clearly distinguishes it from build_swap and submit_swap, which are the natural confusable siblings.

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

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

It states when to call (after submission, after a timeout), how to call repeatedly ('Poll this ID with backoff within the account rate limit'), and explicitly routes the agent elsewhere for a related need ('use get_trading_usage for aggregate volume'). Exclusions and alternatives are named, not 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 already cover readOnly/idempotent/non-destructive, but the description adds meaningful context beyond them: no API key or data credits required (public access), the precise nature of 'enabled' as configuration status rather than a liquidity quote or RPC health check, and the shape of the payload. That negative clarification is exactly the kind of disambiguation annotations cannot express. Slightly short of 5 only because it doesn't mention caching/TTL semantics of the config itself, despite build TTL being a returned field.

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 action and the reason to call it, then access requirements, then payload contents, then boundary clarifications. Every sentence earns its place and none repeat the schema or annotations.

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?

An output schema exists, so return values need not be enumerated, yet the description still names the key fields and, more importantly, defines 'enabled' and separates configuration status from liquidity and RPC health. Combined with the sibling routing, an agent has everything needed to call this 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?

Zero parameters, so the baseline is 4 and there is nothing for the description to clarify about inputs. The description instead spends its budget on returned fields, which is appropriate rather than a gap.

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 ('Read the current server's swap policy') with the exact downstream purpose ('before choosing build_swap parameters'). It is immediately distinguishable from sibling reads like get_trading_usage and get_access_status. No ambiguity about what is returned versus what this tool is not.

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 routes: use this before calling build_swap, use get_trading_usage for executed volume, use get_access_status for grants. Both the condition for using this tool and the alternatives for adjacent needs are named, leaving nothing to inference.

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

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

Goes well beyond the readOnly/idempotent annotations: bearer key requirement, no credit consumption, the once-per-swap counting rule, decimal-string vs build-time-price formatting, the meaning of available=false, and eventual-consistency lag for new receipts. These are exactly the operational details 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?

Purpose is front-loaded in the first sentence, followed by routing guidance, then behavioral caveats. Every sentence carries distinct information; nothing is repeated from the schema or annotations.

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?

An output schema exists so return-value detail is not strictly needed, yet the description still summarizes the return shape (available, totals, by_api_key) and covers auth, cost, counting semantics, and edge cases. Complete for an agent to call and interpret 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline is 4. The description correctly does not waste space restating a nonexistent 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+resource+scope: 'Read all-time executed volume for the authenticated account and each API key.' It explicitly distinguishes itself from get_recent_trades (market history) and get_swap_status (one receipt), so an agent can route 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 use case ('use for accounting') and names both excluded alternatives with the reason each is wrong for this need. No inference required to pick between the three siblings.

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 with openWorldHint=false, so safety is covered. The description adds genuinely new behavioral context: it is public with no key or credits required, and it explains the '-1 credits means Unlimited' sentinel and the sales_enabled gating that determines whether a purchase path exists at all.

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 purpose, then access model, then return fields, then the next action - a logical progression with no filler sentences. It runs longer than strictly necessary given the output schema already enumerates the returned fields, but each sentence still carries operational meaning.

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

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

The tool has no parameters and a rich output schema, so the description only needs to supply access requirements, sentinel semantics, and workflow routing - and it delivers all three. 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?

Zero parameters, so the baseline is 4; there is nothing for the description to disambiguate. The field-level detail it provides (USDC 6-decimal pricing, duration, event allowance, request/connection limits) describes outputs rather than inputs and is partly redundant with the output 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 ('List current data packages and prices') and immediately scopes the purpose ('before buying a live-data subscription'). An agent can distinguish it from sibling inventory tools like get_trading_config or get_payment_instructions 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?

Explicitly says when to call it (before buying a subscription), when it is unnecessary ('Trading alone needs no data package'), and what to do next ('choose a plan and call get_payment_instructions with its exact id'). The alternative tool is named by name.

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 readOnlyHint/idempotentHint true and destructiveHint false, and the description is consistent with that (it does not sign, submit or activate). Beyond the annotations it discloses auth needs (bearer key), that no package/data credits are needed, the return artifacts (base64 legacy Solana transaction, last_valid_block_height), fee/rent requirements (USDC + SOL), the private-key custody guarantee, and 409/blockhash-expiry semantics.

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 then a logical progression of auth, return value, review step, signing/broadcast responsibility, and error handling. It is on the longer side for a single-parameter tool, but nearly every sentence carries operational guidance, so there is 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?

Covers purpose, preconditions, auth, return artifacts, the review step, who signs/broadcasts, error semantics, and the follow-up call. Even though an output schema exists, the description supplies the workflow context an agent needs to invoke this costly-to-get-wrong transaction step safely.

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

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

Only one parameter and schema coverage is 100%, so the schema already fully documents invoice_id (pattern, example, and 'not a swap id or signature'). The description adds invoice-level preconditions (must be unpaid and unexpired) but no additional syntax or format meaning. Baseline 3 is appropriate when the schema carries the parameter 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 (Prepare) plus resource (unsigned USDC payment for an invoice) and scopes it to 'existing unpaid, unexpired invoice.' It differentiates from siblings by naming get_invoice_status and confirm_invoice_payment and clarifying that it neither signs, submits, nor activates the package.

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

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

Explicit when-to-use and when-not: only for existing unpaid/unexpired invoices, next call confirm_invoice_payment with the broadcast signature, and a 409 means expired/paid. It also routes the agent to get_invoice_status for review and gives a handling rule for blockhash expiry to avoid double payment.

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 destructive/openWorld/idempotent, and the description reinforces these with substance rather than repetition: 'This can spend funds', 'submitted is not confirmation', and an explanation of idempotency semantics ('Repeating the same ID and signed bytes cannot create a different trade'). It also discloses the auth requirement (Bearer key) and the retry/timeout policy.

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 action and the money-spending warning, then prerequisites, then failure handling. Dense but each clause carries operational weight; the line-broken formatting is slightly awkward for a description field 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 destructive, authenticated broadcast tool, the description covers purpose, auth, input provenance, idempotency, failure handling, and the distinction between submission and confirmation. An output schema exists, yet the description still briefly notes the return shape (swap ID, signature, status) without over-explaining.

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 in detail, establishing a baseline of 3. The description adds cross-tool meaning: 'Only the exact build_swap message is accepted' and the requirement that the wallet must already have authorized its amounts and costs, which clarifies why the signed bytes must be unmodified.

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: 'Broadcast the wallet-approved, signed build through Kolibrio.' It immediately distinguishes itself from the sibling build_swap by emphasizing that the transaction is already built, signed and approved, and it flags the money-spending nature up front.

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

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

Explicitly states prerequisites ('Requires a Bearer key for the account that built the swap', 'Only the exact build_swap message is accepted') and post-conditions with a named alternative: 'After a timeout or uncertain delivery, poll get_swap_status; never automatically build a replacement or change its blockhash.' This is a clear when-to-use / when-not-to-use / what-to-do-instead set.

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