PipRail

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

The description reinforces the readOnlyHint and idempotentHint by stating 'Read-only; moves no funds.' It also goes beyond annotations by noting that the time envelope is in-memory for this process while money/count totals persist only if a spend store is configured.

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

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

The description is notably verbose and repetitive: the list of remaining amounts, totals, leashes, and envelopes appears more than once in similar wording. It could be compressed into one or two clear sentences without losing 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?

An output schema exists, there are no input parameters, and the description provides the key behavioral caveat about persistence. Some terms like 'time leash' are jargon-heavy, but the overall context is sufficient for an agent to use this read-only budget check.

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?

There are zero parameters and the schema fully covers that fact, so the baseline of 4 applies. No per-parameter explanation is possible or needed.

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 clearly states the tool reads spend budget and time-leash remaining across networks/assets and totals. It is not tautological and distinguishes a budget-checking action from the payment/quote siblings, though jargon and repeated phrasing keep it from a perfect 5.

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 explicitly instructs to use it in Mode A (headless) to self-check before paying, which gives clear when-to-use guidance. It does not explicitly contrast with sibling tools such as quote or pay, but the 'BEFORE paying' instruction is practical and specific enough.

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 readOnlyHint annotation, the description discloses that results are cross-scheme, that advertised prices are not live, and that a quote must re-chec the price before payment. This gives the agent important behavioral context about staleness and follow-up requirements that annotations alone do not 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?

The description is compact and front-loaded: it opens with the core purpose and 'WITHOUT paying', then covers defaults, and closes with the mandatory workflow. Every sentence carries operational value with no filler or repetition.

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 9 optional parameters, no output schema, and a discovery use case, the description gives enough to invoke correctly: default network behavior, key parameter semantics, and the required follow-up. The exact result shape is not documented, but for a list-style discovery tool this is not necessary to call it correctly.

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

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

Even though schema coverage is 100%, the description adds significant semantic value: 'relevance' default with query vs first-seen otherwise, multi-word query fan-out, 'self' default for network, 'advertised' USD price for maxPrice, 'strict' for category, and 'unscored pass' for minReliability. These nuances go well beyond the raw schema descriptions.

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

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

The description uses a specific verb ('Find') on a clear resource ('x402 payment-gated resources on the OPEN indexes') and immediately scopes it as a discovery action with 'WITHOUT paying'. It distinguishes itself from the sibling payment tools by framing the use case as 'what can I buy?' and routing subsequent steps to quote/pay.

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 explicitly says when to use the tool ('to answer what can I buy?') and gives the search-then-quote-then-pay workflow. It also clarifies the default network scoping ('network='self'' vs 'any'), and explicitly instructs the agent to always call piprail_quote_payment before piprail_pay_request, effectively stating what this tool is not for.

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?

The description states 'Read-only' and the annotations declare readOnlyHint and idempotentHint as true, with no contradiction. It adds value by clarifying the tool is informational and safe to call repeatedly, though it does not deeply elaborate on side effects beyond being read-only.

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

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

The description is compact and well-structured, using a dash-separated list of topics to convey scope efficiently. Every sentence adds information; there is no redundancy or filler.

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

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

For a documentation/guide tool with no parameters and no output schema, the description provides sufficient context: what it does, what topics it covers, and when to call it. No additional information is needed for correct usage.

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 has no parameters, so parameter-level explanation is unnecessary. The description fully covers the tool's interface by implying no inputs are needed; the baseline for zero-parameter tools is met.

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 clearly states the tool's purpose with a specific verb ('Read') and resource ('PipRail agent contract'), and enumerates the exact topics covered. It is easily distinguished from sibling tools like piprail_pay_request or piprail_quote_payment because it is explicitly a guide/reference rather than an action tool.

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

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

The description gives explicit usage guidance: 'call it once if unsure how to use these tools.' It also explains what content the user will learn (quote→plan→pay loop, refusals, terminal declines, re-pay rule, modes), which helps the agent decide when to invoke it.

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 destructiveHint=true, readOnlyHint=false, and idempotentHint=false. The description adds valuable context: it discloses that funds may move, explains the two rails (on-chain vs exact), details the refusal case (declined: true with no funds moved), and notes the payment receipt. This goes beyond the annotations and gives the agent a clear model of side effects and failure modes.

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

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

The description is information-dense but every sentence earns its place: it states the core action, explains the rail variability, lists the return values, and covers the decline case. It is front-loaded with the main purpose and avoids redundancy. No fluff or filler.

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

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

With no output schema, the description must explain return values, and it does: HTTP status, response body, payment receipt, and the declined object. It also covers side effects and rail behavior. It lacks explicit error handling (e.g., network failures, invalid URL) but these are standard and not critical for a payment tool. Overall, it is sufficiently complete for an agent to call it correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (url, body, method). The description does not add parameter-level detail beyond the schema, but it does imply the url is an x402 payment-gated URL, which is a slight enhancement. Overall, it meets the baseline for full schema coverage.

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 clearly states the verb (fetch/pay), the resource (x402 payment-gated URL), and the action (automatically making payment). It distinguishes itself from siblings by being the execution tool for payment, while siblings like quote_payment and plan_payment are pre-payment steps. The mention of rail types and the return cases adds specificity.

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

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

The description implies this is the tool to actually execute payment, but does not explicitly state when to use it versus siblings (e.g., after quoting or planning). It mentions the spend policy and approval hook as constraints, but offers no exclusions or alternative routing. An agent would infer usage from the sibling names and the tool's action, but explicit guidance is missing.

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 indicate readOnlyHint=true and openWorldHint=true, and the description adds substantial behavioral context: it reads wallet balance, native gas, and recipient capability, and it explains the meaning of key return fields like fundingHint. This goes well beyond the annotations and clearly communicates what the tool does and does not do.

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

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

The description is efficiently structured: it opens with the core purpose, then explains the return structure and usage context, and ends with a clear call-to-action. Every sentence adds value with no redundancy or fluff.

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

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

Given the tool's simplicity (one parameter), the presence of an output schema, and the detailed explanation of return semantics and usage context, the description is complete. It even explains the meaning of key fields beyond what the schema might offer, making it fully self-sufficient for an agent to decide when and how to call it.

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

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

Schema description coverage is 100% for the only parameter (url), so the schema already fully documents it. The description doesn't add parameter-specific details beyond what the schema provides, which meets the baseline for high coverage.

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 ('Check'), a resource ('x402-gated URL'), and the scope ('across every rail the URL offers on your chain'). It also distinguishes itself from siblings by explicitly mentioning piprail_pay_request as the follow-up, making its purpose unambiguous.

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

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

The description gives explicit when-to-use guidance: 'Call this before piprail_pay_request so you never commit to a payment you cannot finish.' It also clarifies the behavioral implications of the return values (payable:false means do NOT attempt payment) and the gated:false case, leaving no ambiguity about appropriate usage.

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=true and openWorldHint=true. The description adds valuable behavioral detail: it returns amount, token, chain, recipient, and spend policy status, and handles ungated URLs with { gated: false }. It also clarifies the tool does not pay. This goes beyond the annotations, though it omits potential rate limits or error scenarios; still, for a quote tool this is adequate.

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

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

Two sentences with no filler. The first sentence states the core action and return values; the second adds the gated:false edge case and usage guidance. The description is front-loaded with purpose and ends with actionable advice. Every sentence 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?

The tool has an output schema (though not shown) and the description enumerates the key return fields (amount, token, chain, recipient, spend policy, gated:false). Combined with annotations and a single well-defined parameter, nothing essential is missing for an agent to decide when and how to call this tool. The usage guidance also covers the decision flow.

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% for the single parameter 'url', which is described as 'Full URL of the gated resource.' The description does not add further parameter-level detail, but none is needed since the schema already fully documents it. Baseline of 3 applies due to high schema coverage; no extra compensation required.

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 clearly states the tool's action: 'Get the price of an x402 payment-gated URL WITHOUT paying.' It specifies the resource type (payment-gated URL) and explicitly notes it does not execute a payment, distinguishing it from payment-related siblings like piprail_plan_payment and piprail_pay_request. The scope is precise and immediately understandable.

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

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

The description explicitly instructs 'Call this first to decide whether a resource is worth buying,' providing clear guidance on when to use the tool. It also implies the alternative path (paying) via the mention of 'WITHOUT paying' and the presence of sibling tools for payment actions. This gives an agent a direct decision 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?

The description explicitly discloses that the tool 'Moves no funds; nothing is PipRail-hosted', explains the return shape ('Returns one outcome per index'), and notes that a listing is 'pending review'. This goes well beyond the annotations, which only state readOnlyHint/destructiveHint.

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

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

The description is a single dense paragraph with many clauses and a long parenthetical NOTE. It contains useful information but is wordy and somewhat repetitive (e.g., 'x402', 'index'). It could be trimmed while preserving the key points.

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 description covers the essential aspects: purpose, default target, free registration, pending review, return format, and a critical caveat about 'exact' clients. There is no output schema to describe, and the description is sufficient for an agent to understand the tool's role.

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 schema already covers all 10 parameters with detailed descriptions (100% coverage). The tool description adds no parameter-specific meaning beyond what the schema provides, 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 clearly states the action ('List an x402 payment-gated resource YOU run') and the target ('on the open indexes so other agents can discover it'). It explicitly distinguishes this tool from siblings like discover and pay, and the context signals list sibling tools that serve different purposes.

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

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

The description provides usage context: it is for resources you run, defaults to 402 Index, mentions no auth/payment, and gives specific guidance on making the listing payable with an 'exact' rail. It doesn't explicitly say when NOT to use it or contrast with discover, but the purpose is clear enough.

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 readOnlyHint and idempotentHint annotations, the description discloses concrete behavioral details: it is wallet-free, re-derives onChain.payer from the transaction, and interprets matchesClaims:false as indicating a forged payer. It also explains why rpcUrl may be needed for non-default chains, adding meaningful operational transparency.

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

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

The description is information-dense but remains structured around purpose, usage, and return semantics. Some repetition of concepts like 'VERIFIABLE' and 'confirm payment settled' adds slight redundancy, but every sentence contributes necessary detail and the flow is logical.

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

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

Since there is no output schema, the description compensates by explaining the key return fields (ok, onChain, matchesClaims, ageSeconds, error?) and their meanings. It also covers the main error scenario (forged payer) and the optional RPC parameter, giving the agent enough context to call the tool 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?

Both parameters are described in the schema (100% coverage), and the description adds extra meaning by specifying the receipt's internal shape ({ piprail, receipt, resource, decimals? }) and the purpose of rpcUrl (for chains outside common presets). This goes beyond the basic schema and reduces ambiguity for callers.

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 clearly states the action (re-verify a PipRail verifiable receipt against the chain), the resource (receipt), and the intended outcome (confirm payment actually settled). It also distinguishes itself from receipt creation by referencing piprail_pay_request's verifiableReceipt and framing this as a verification step.

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

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

The description explains when to use the tool: whenever a receipt needs to be re-verified independently of the party that provided it, and notes that it is read-only and wallet-free. It does not explicitly enumerate sibling alternatives, but the context and explicit reference to pay_request's receipt make the appropriate usage clear.

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