@piprail/sdk 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@piprail/sdk` are documented here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
 versions follow [Semantic Versioning](https://semver.org/).
 
+## [1.8.0] — 2026-06-06
+
+### Added
+- **Agent tool annotations.** Each of the five `paymentTools(client)` descriptors now carries an
+  advisory `annotations` object (MCP-style `ToolAnnotations`: `title`, `readOnlyHint`,
+  `destructiveHint`, `idempotentHint`, `openWorldHint`), so an MCP client or agent can reason about a
+  tool's nature and render the right consent. The three reads (`piprail_discover` / `quote` / `plan`)
+  are flagged **read-only**; `piprail_pay_request` is flagged **value-moving** (not read-only,
+  destructive, non-idempotent) so a client can surface that it's the one tool that spends;
+  `piprail_register` writes a listing but is non-destructive. New exported type `ToolAnnotations`.
+  Backward-compatible — `annotations` is optional and non-MCP runtimes ignore it. (`@piprail/mcp`
+  ≥ 0.2.2 passes them through on the wire.)
+
 ## [1.7.0] — 2026-06-06
 
 ### Added
@@ -479,6 +492,7 @@ straight into your wallet. The API is small and self-contained.
   to your wallet; PipRail never holds funds.
 - `viem ^2.21` is a peer dependency. Node 20+ or a modern browser.
 
+[1.8.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.7.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.6.0]: https://www.npmjs.com/package/@piprail/sdk
 [1.5.1]: https://www.npmjs.com/package/@piprail/sdk

package/README.md

@@ -113,9 +113,15 @@ For **every rail the 402 offers on your chain**, the plan reads **token balance
 
 ```ts
 import { paymentTools } from '@piprail/sdk'
-const tools = paymentTools(client) // → [piprail_quote_payment, piprail_plan_payment, piprail_pay_request]
+const tools = paymentTools(client) // → [piprail_discover, piprail_quote_payment, piprail_plan_payment, piprail_pay_request, piprail_register]
 ```
 
+Each descriptor also carries advisory **`annotations`** (MCP-style `ToolAnnotations` — `title`,
+`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`): the three reads are flagged
+**read-only**, `piprail_pay_request` is flagged **value-moving** (the one tool that spends), and
+`piprail_register` is non-destructive — so an MCP client can render the right consent. They're hints,
+not the boundary; the spend policy is. `@piprail/mcp` advertises them on the wire.
+
 See [`examples/agent-tools.mjs`](../examples/agent-tools.mjs) for MCP / AI-SDK wiring.
 
 ## Be discoverable — find and be found ($0, no backend)
@@ -162,6 +168,11 @@ const hits = await client.discover({ query: 'weather', maxPrice: 0.01 })
 const res = await client.fetch(hits[0].resource) // then quote → plan → pay as usual
 ```
 
+`network` defaults to `'self'` (your chain only); pass `'any'` to search every chain, or a CAIP-2 id
+(`'eip155:8453'`) for a specific one. Chain slugs map to CAIP-2 through the `SLUG_TO_CAIP2` table —
+adding a chain adds one entry there (see [DISCOVERY.md](./DISCOVERY.md) §2.5), and an unresolved
+network is kept, never hidden.
+
 **3) Emit a discovery file** — turn your gate's config into the artifacts a crawler reads (pure, no
 I/O); serve the result as a static file on **your own** origin:
 
@@ -173,11 +184,13 @@ const openapi = buildOpenApi({
   origin: 'https://api.example.com',
   resources: [await gate.describe('https://api.example.com/report')],
 })
-// serve `openapi` at https://api.example.com/openapi.json  (the OpenAPI-first convention indexes parse)
+// serve `openapi` at https://api.example.com/openapi.json — each priced op carries an `x-payment-info`
+// block (the field indexes crawl) plus a default root `x-generator` attribution stamp.
 // buildWellKnownX402(...) emits the legacy /.well-known/x402 file; buildX402DnsTxt(...) the _x402 DNS line
 ```
 
-For an LLM/MCP this is two tools: **`piprail_discover`** (find) and **`piprail_register`** (be found).
+For an LLM/MCP these are two more tools — **`piprail_discover`** (find) and **`piprail_register`**
+(be found) — on top of the three payment tools, so `paymentTools(client)` / `@piprail/mcp` expose **five**.
 
 > **Two honest caveats.** The open indexes assume the mainstream `exact` scheme, so to be *usefully*
 > listed also offer a standard `exact` USDC rail on Base/Solana (`discover()` results are

package/dist/index.cjs

@@ -2040,6 +2040,13 @@ function paymentTools(client) {
     {
       name: "piprail_discover",
       description: `Find x402 payment-gated resources on the OPEN indexes (a phone book of payable APIs) WITHOUT paying. Use it to answer "what can I buy?" \u2014 search by topic, then quote/plan/pay a chosen one. By default returns only resources payable on your wallet's chain (network='self'); pass 'any' for every chain. Results are cross-scheme: ALWAYS call piprail_quote_payment on a chosen resource (it re-checks the live price) before piprail_pay_request.`,
+      annotations: {
+        title: "Discover payable x402 APIs",
+        readOnlyHint: true,
+        // reads the open indexes only; never pays
+        openWorldHint: true
+        // reaches external indexes (402 Index, CDP Bazaar)
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2076,6 +2083,13 @@ function paymentTools(client) {
     {
       name: "piprail_quote_payment",
       description: "Get the price of an x402 payment-gated URL WITHOUT paying. Returns the amount, token, chain, recipient, and whether it is within the spend policy. Returns { gated: false } when the URL needs no payment. Call this first to decide whether a resource is worth buying.",
+      annotations: {
+        title: "Quote an x402 price",
+        readOnlyHint: true,
+        // reads the 402 challenge; never pays
+        openWorldHint: true
+        // fetches an arbitrary URL
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2092,6 +2106,13 @@ function paymentTools(client) {
     {
       name: "piprail_plan_payment",
       description: "Check whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive \u2014 across every rail the URL offers on your chain \u2014 and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.",
+      annotations: {
+        title: "Plan an x402 payment",
+        readOnlyHint: true,
+        // reads balances + the challenge; never pays
+        openWorldHint: true
+        // fetches a URL and reads chain state
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2130,6 +2151,17 @@ function paymentTools(client) {
     {
       name: "piprail_pay_request",
       description: "Fetch an x402 payment-gated URL, automatically paying the required on-chain payment if needed (subject to the spend policy + approval hook). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
+      annotations: {
+        title: "Pay an x402 request",
+        readOnlyHint: false,
+        // this is the one tool that MOVES FUNDS
+        destructiveHint: true,
+        // an on-chain payment is value-moving and not reversible
+        idempotentHint: false,
+        // paying twice = two payments
+        openWorldHint: true
+        // fetches a URL and settles on-chain
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2180,6 +2212,16 @@ function paymentTools(client) {
     {
       name: "piprail_register",
       description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; searchable within seconds. Returns one outcome per index ({ source, ok, detail }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      annotations: {
+        title: "Register an x402 endpoint",
+        readOnlyHint: false,
+        // writes a listing to an external index
+        destructiveHint: false,
+        // adds a listing; nothing is destroyed and no funds move
+        openWorldHint: true
+        // posts to external indexes (402 Index)
+        // idempotentHint intentionally omitted — index dedup behaviour isn't guaranteed.
+      },
       parameters: {
         type: "object",
         properties: {

package/dist/index.d.cts

@@ -4636,6 +4636,25 @@ declare class PipRailClient {
  */
 declare function planAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<PaymentPlan | null>;
 
+/**
+ * MCP-style tool annotations — optional, advisory hints that let an MCP client or
+ * agent reason about a tool's *nature* (is it safe to call freely? does it move
+ * value?). They mirror the MCP spec's `ToolAnnotations`. NOTE: hints only — a
+ * client must never make a security decision solely on these; the spend policy is
+ * the real boundary.
+ */
+interface ToolAnnotations {
+    /** Human-friendly title for the tool. */
+    title?: string;
+    /** True when the tool only READS — no state change, no funds moved. */
+    readOnlyHint?: boolean;
+    /** True when the tool may move value or do something not easily undone (only meaningful when not read-only). */
+    destructiveHint?: boolean;
+    /** True when calling repeatedly with the same args has no additional effect. */
+    idempotentHint?: boolean;
+    /** True when the tool reaches the open world — external indexes, chains, or arbitrary URLs. */
+    openWorldHint?: boolean;
+}
 /** A framework-agnostic tool definition an agent runtime can register. */
 interface AgentTool {
     /** Unique tool name (snake_case, namespaced `piprail_…`). */
@@ -4644,6 +4663,8 @@ interface AgentTool {
     description: string;
     /** JSON Schema (draft-07 object) describing the arguments. */
     parameters: Record<string, unknown>;
+    /** Advisory MCP-style hints about the tool's nature (read-only, value-moving, …). */
+    annotations?: ToolAnnotations;
     /** Execute the tool. Returns a JSON-serialisable result. */
     invoke: (args: Record<string, unknown>) => Promise<unknown>;
 }
@@ -5296,4 +5317,4 @@ declare function encodeXPaymentHeader(input: {
     x402Version?: number;
 }): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };

package/dist/index.d.ts

@@ -4636,6 +4636,25 @@ declare class PipRailClient {
  */
 declare function planAcross(clients: PipRailClient[], url: string, init?: RequestInit): Promise<PaymentPlan | null>;
 
+/**
+ * MCP-style tool annotations — optional, advisory hints that let an MCP client or
+ * agent reason about a tool's *nature* (is it safe to call freely? does it move
+ * value?). They mirror the MCP spec's `ToolAnnotations`. NOTE: hints only — a
+ * client must never make a security decision solely on these; the spend policy is
+ * the real boundary.
+ */
+interface ToolAnnotations {
+    /** Human-friendly title for the tool. */
+    title?: string;
+    /** True when the tool only READS — no state change, no funds moved. */
+    readOnlyHint?: boolean;
+    /** True when the tool may move value or do something not easily undone (only meaningful when not read-only). */
+    destructiveHint?: boolean;
+    /** True when calling repeatedly with the same args has no additional effect. */
+    idempotentHint?: boolean;
+    /** True when the tool reaches the open world — external indexes, chains, or arbitrary URLs. */
+    openWorldHint?: boolean;
+}
 /** A framework-agnostic tool definition an agent runtime can register. */
 interface AgentTool {
     /** Unique tool name (snake_case, namespaced `piprail_…`). */
@@ -4644,6 +4663,8 @@ interface AgentTool {
     description: string;
     /** JSON Schema (draft-07 object) describing the arguments. */
     parameters: Record<string, unknown>;
+    /** Advisory MCP-style hints about the tool's nature (read-only, value-moving, …). */
+    annotations?: ToolAnnotations;
     /** Execute the tool. Returns a JSON-serialisable result. */
     invoke: (args: Record<string, unknown>) => Promise<unknown>;
 }
@@ -5296,4 +5317,4 @@ declare function encodeXPaymentHeader(input: {
     x402Version?: number;
 }): string;
 
-export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };
+export { type AcceptOption, type AddressId, type AgentTool, type AlgorandToken, type AptosToken, type AssetId, type BuildExactParams, CHAINS, type Caip2, type ChainFamily, type ChainInput, type ChainName, type ChainPreset, type ChainSelector, type ConfirmInfo, ConfirmationTimeoutError, type CostEstimate, type DiscoverOptions, type DiscoveredRail, type DiscoveredResource, type DiscoverySigner, type DiscoverySource, EIP3009_TYPES, EXACT_NETWORK_SLUGS, type EvmToken, type ExactAccept, type ExactAuthorization, type ExpressLikeMiddleware, type ExpressLikeNext, type ExpressLikeRequest, type ExpressLikeResponse, GENERATOR, InsufficientFundsError, InvalidEnvelopeError, type ManifestInput, MaxRetriesExceededError, MissingDriverError, type NearToken, NoCompatibleAcceptError, NonReplayableBodyError, type OpenApiDocument, type OpenApiOperation, type PayBlocker, type PayOption, type PayWarning, PaymentDeclinedError, type PaymentDriver, type PaymentGate, type PaymentIntent, type PaymentPlan, type PaymentPolicy, type PaymentRail, PaymentTimeoutError, PipRailClient, type PipRailClientOptions, type PipRailCostQuote, PipRailError, type PipRailEvent, type PipRailQuote, type PolicyDecision, RecipientNotReadyError, type RecipientReason, type RegisterInput, type RegisterOptions, type RegisterOutcome, type RequirePaymentOptions, type ResolveOptions, type ResolvedChain, type ResolvedNetwork, type ResolvedToken, type ResourceDescription, type SearchOpenIndexesOptions, type SolanaToken, type SpendAssetTotal, type SpendRecord, type SpendSummary, type StellarToken, type SuiToken, type TokenInfo, type TokenInput, type TonToken, type ToolAnnotations, type TronToken, UnknownTokenError, UnsupportedNetworkError, type VerifyErrorCode, type VerifyPaymentResult, type VerifyResult, type WalletBalance, type WalletHandle, type WalletInput, type WellKnownX402, WrongChainError, WrongFamilyError, type X402AcceptEntry, type X402Challenge, type X402DnsRecord, type X402InvalidBody, type X402PaymentSignature, type X402Receipt, type X402ResourceObject, type XrplToken, buildChallengeHeader, buildExactAuthorization, buildOpenApi, buildReceiptHeader, buildSignatureHeader, buildWellKnownX402, buildX402DnsTxt, chainIdForExactNetwork, createPaymentGate, encodeXPaymentHeader, evaluatePolicy, normalizeNetwork, parseChallenge, parseExactRequirements, parseReceipt, parseSignatureHeader, paymentTools, pickAccept, planAcross, register402Index, registerDriver, registerX402Scan, requirePayment, resolveChain, searchOpenIndexes, toInsufficientFundsError, toInvalidBody };

package/dist/index.js

@@ -2040,6 +2040,13 @@ function paymentTools(client) {
     {
       name: "piprail_discover",
       description: `Find x402 payment-gated resources on the OPEN indexes (a phone book of payable APIs) WITHOUT paying. Use it to answer "what can I buy?" \u2014 search by topic, then quote/plan/pay a chosen one. By default returns only resources payable on your wallet's chain (network='self'); pass 'any' for every chain. Results are cross-scheme: ALWAYS call piprail_quote_payment on a chosen resource (it re-checks the live price) before piprail_pay_request.`,
+      annotations: {
+        title: "Discover payable x402 APIs",
+        readOnlyHint: true,
+        // reads the open indexes only; never pays
+        openWorldHint: true
+        // reaches external indexes (402 Index, CDP Bazaar)
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2076,6 +2083,13 @@ function paymentTools(client) {
     {
       name: "piprail_quote_payment",
       description: "Get the price of an x402 payment-gated URL WITHOUT paying. Returns the amount, token, chain, recipient, and whether it is within the spend policy. Returns { gated: false } when the URL needs no payment. Call this first to decide whether a resource is worth buying.",
+      annotations: {
+        title: "Quote an x402 price",
+        readOnlyHint: true,
+        // reads the 402 challenge; never pays
+        openWorldHint: true
+        // fetches an arbitrary URL
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2092,6 +2106,13 @@ function paymentTools(client) {
     {
       name: "piprail_plan_payment",
       description: "Check whether you CAN pay an x402-gated URL before paying. Reads your wallet balance, native gas, and whether the recipient can receive \u2014 across every rail the URL offers on your chain \u2014 and returns { gated, payable, best, options, fundingHint }. payable:false means do NOT attempt the payment; fundingHint says exactly what to top up. Call this before piprail_pay_request so you never commit to a payment you cannot finish. Returns { gated: false } when no payment is needed.",
+      annotations: {
+        title: "Plan an x402 payment",
+        readOnlyHint: true,
+        // reads balances + the challenge; never pays
+        openWorldHint: true
+        // fetches a URL and reads chain state
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2130,6 +2151,17 @@ function paymentTools(client) {
     {
       name: "piprail_pay_request",
       description: "Fetch an x402 payment-gated URL, automatically paying the required on-chain payment if needed (subject to the spend policy + approval hook). Returns the HTTP status, the response body, and a payment receipt if one settled. If the payment is refused by policy or the approval hook, returns { declined: true, reason } \u2014 no funds moved.",
+      annotations: {
+        title: "Pay an x402 request",
+        readOnlyHint: false,
+        // this is the one tool that MOVES FUNDS
+        destructiveHint: true,
+        // an on-chain payment is value-moving and not reversible
+        idempotentHint: false,
+        // paying twice = two payments
+        openWorldHint: true
+        // fetches a URL and settles on-chain
+      },
       parameters: {
         type: "object",
         properties: {
@@ -2180,6 +2212,16 @@ function paymentTools(client) {
     {
       name: "piprail_register",
       description: "List an x402 payment-gated resource YOU run on the open indexes so other agents can discover it. Default target is 402 Index \u2014 no auth, no signature, no payment; searchable within seconds. Returns one outcome per index ({ source, ok, detail }); a step the chain can't satisfy comes back ok:false with the reason. Moves no funds; nothing is PipRail-hosted.",
+      annotations: {
+        title: "Register an x402 endpoint",
+        readOnlyHint: false,
+        // writes a listing to an external index
+        destructiveHint: false,
+        // adds a listing; nothing is destroyed and no funds move
+        openWorldHint: true
+        // posts to external indexes (402 Index)
+        // idempotentHint intentionally omitted — index dedup behaviour isn't guaranteed.
+      },
       parameters: {
         type: "object",
         properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piprail/sdk",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Accept x402 crypto payments across 28 chains — every major EVM chain plus Solana, TON, Tron, NEAR, Sui, Aptos, Algorand, Stellar & XRPL — in a couple of lines. No backend, no database, no fee; payments settle straight to your wallet.",
   "type": "module",
   "main": "./dist/index.cjs",