Skip to main content
Glama
PaulieB14

PayQL

by PaulieB14
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

PayQL

Let any AI agent query The Graph and pay per query in USDC — gasless, keyless, bring-your-own-wallet.

▶ Try it live: payql-playground-production.up.railway.app — pick a question, see the exact subgraph + GraphQL query for free, then run it for $0.01 with your own wallet. (playground source)

PayQL is an MCP server. Drop it into any MCP-capable harness (Claude Desktop, Claude Code, Cursor, …) and your agent can discover the right subgraph, see the price, and pull live on-chain data — paying ~$0.01 in USDC per query over x402, with no API key, no account, and no ETH for gas.

It's the missing glue between an agent harness (which brings the wallet) and The Graph's data (which is now pay-per-query). The hard part — which of 40 forks is the live subgraph? — is solved by ranking discovery on on-chain curation signal.

Why this exists

The Graph's gateway now speaks x402: an unpaid request gets a 402 Payment Required, the caller signs a USDC payment authorization, and the data comes back. No Studio signup, no key management — the payment is the auth. PayQL wires that pay-per-query loop into the agent's tool surface and adds the two things an agent actually needs around it: finding the right subgraph, and not overspending.

  • Gasless. Payments use EIP-3009 transferWithAuthorization (the exact scheme on Base). You sign off-chain; the facilitator submits the tx and pays gas. A USDC-only wallet is enough — no ETH.

  • Keyless. The x402 gateway path needs no API key or account.

  • Wallet-agnostic. PayQL just speaks x402 — which wallet pays is config. BYO key, a managed/capped wallet (e.g. Ampersend), or hand the 402 to a wallet-equipped harness. Same code path.

  • Bounded & predictable. Queries are ~$0.01, and the per-query cap defaults to $0.01 — so an agent never pays more than the going rate. A price preflight and a clear "fund your wallet" message round it out.

Related MCP server: 🍋 LemonCake — Billing & budgets for AI agents

How it works

agent → search_subgraphs("uniswap v3")     → ranked live subgraphs (+ ids)
      → get_payment_info(id)                → "$0.01 USDC" (no payment)
      → query_subgraph(id, "{ ... }")       → data + receipt (tx hash, amount)

Discovery is ranked by on-chain curation signal (a popularity proxy) so you get the live, used subgraph, not a dead fork.

Releasing

npm version patch      # bump package.json
# match skill/skill.json to it, then:
npm publish
npm run publish:skill  # ClawHub — reads the slug and version from skill.json

npm run publish:skill exists because two things are easy to get wrong by hand and both are mechanical: the ClawHub slug is payqlskill, not payql (the first publish ran from a folder called skill, and payql now redirects here — a plain clawhub publish . fails with "Slug redirects to an existing skill"), and package.json and skill/skill.json drifted once already, so npm and ClawHub advertised different versions of the same tool. The script refuses to publish when the two versions disagree, and takes the slug from skill.json rather than from memory.

Tools

Tool

Cost

What it does

search_subgraphs

~$0.01 (x402) †

Find live subgraphs by keyword/protocol, ranked by curation signal. Returns subgraph_id, ipfsHash, signal, query fees, query URL.

get_payment_info

free

Preflight a subgraph: returns the USDC price, payTo, network and whether it's within your cap — without paying.

query_subgraph

~$0.01 (x402)

Run a GraphQL query, paying via x402. Returns the data + a payment receipt. Enforces the spend cap; returns a fund-wallet message if balance is short.

get_subgraph_schema

~$0.01 (x402)

List a subgraph's root queryable entities (GraphQL introspection of the target subgraph).

wallet_status

free

Payment mode, wallet address, USDC/ETH balance, spend cap, funding instructions. Never reveals the key.

x402 is the only payment — there are no API keys, subscriptions, or platform fees. A ~$0.01 row just means that call runs a GraphQL query through the gateway, billed as the same per-query x402 micropayment; get_payment_info and wallet_status don't touch the gateway, so they're free.

† search_subgraphs becomes free when PAYQL_REGISTRY_URL points at a free discovery source (e.g. your own subgraph registry). get_subgraph_schema introspects through the gateway, so it's always an x402 query.

Example — end to end

A typical agent loop is discover → price → query. Tool calls take JSON arguments; results come back as JSON. (The get_payment_info output below is a real preflight against the live gateway; search/query payloads are abridged for illustration.)

1. Find the right subgraph

// call → search_subgraphs
{ "query": "uniswap v3", "first": 3 }
// result (abridged) — ranked by on-chain curation signal
{
  "ok": true,
  "source": "x402:graph-network-subgraph",
  "count": 3,
  "results": [
    {
      "displayName": "Uniswap V3",
      "subgraphId": "5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV",
      "ipfsHash": "QmZ...",
      "currentSignalledTokensGRT": 48210.5,
      "queryFeesGRT": 1203.7,
      "categories": ["DeFi", "DEX"],
      "queryUrl": "https://gateway.thegraph.com/api/x402/subgraphs/id/5zvR82Qo..."
    }
  ],
  "payment": { "paid": true, "amountUsd": 0.01, "txHash": "0x9f…", "network": "eip155:8453" }
}

2. Check the price — free, no payment

// call → get_payment_info
{ "subgraph_id": "5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV" }
// result — real live preflight; the price comes from the 402 challenge
{
  "ok": true,
  "paywalled": true,
  "priceUsd": 0.01,
  "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "payTo": "0x79DC34E41B2b591078d3dE222C43EcaaBD52FcCB",
  "network": "eip155:8453",
  "scheme": "exact",
  "withinCap": true,
  "capUsd": 0.01
}

3. Run the query — pays $0.01 USDC, gasless

// call → query_subgraph
{
  "subgraph_id": "5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV",
  "query": "{ pools(first: 2, orderBy: volumeUSD, orderDirection: desc) { token0 { symbol } token1 { symbol } volumeUSD } }"
}
// result — data + a payment receipt (tx hash + amount actually paid)
{
  "ok": true,
  "data": {
    "pools": [
      { "token0": { "symbol": "USDC" }, "token1": { "symbol": "WETH" }, "volumeUSD": "1234567890.12" },
      { "token0": { "symbol": "WBTC" }, "token1": { "symbol": "WETH" }, "volumeUSD": "987654321.00" }
    ]
  },
  "payment": { "paid": true, "amountUsd": 0.01, "txHash": "0xabc123…", "network": "eip155:8453" }
}

If the wallet is empty, you don't get a silent failure — you get what you owe and how to fund it:

{
  "ok": false,
  "error": "insufficient_funds",
  "message": "Need 0.0100 USDC for this query but the wallet holds 0.0000 USDC.\n\nThis wallet needs USDC on base ... (gasless: USDC only, no ETH) ... Ways to fund: ..."
}

Check the wallet anytime with wallet_status → { "paymentMode": "wallet", "address": "0x…", "usdcBalance": "5.000000", "gaslessPayments": true, "maxUsdPerQuery": 0.01 }

Install

PayQL is on npm — no clone or build required. Add it to your harness and npx fetches it on first run.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "payql": {
      "command": "npx",
      "args": ["-y", "payql"],
      "env": {
        "PAYQL_NETWORK": "base",
        "PAYQL_PRIVATE_KEY": "0xYOUR_BASE_WALLET_KEY",
        "PAYQL_MAX_USD_PER_QUERY": "0.01"
      }
    }
  }
}

Claude Code:

claude mcp add payql \
  -e PAYQL_NETWORK=base \
  -e PAYQL_PRIVATE_KEY=0xYOUR_BASE_WALLET_KEY \
  -e PAYQL_MAX_USD_PER_QUERY=0.01 \
  -- npx -y payql

Cursor — same block as Claude Desktop in ~/.cursor/mcp.json.

Run from source instead? Clone, npm install, npm run build, then point the harness at the local build with "command": "node", "args": ["/ABSOLUTE/PATH/payql/dist/index.js"].

Wallet modes — BYO, harness, or managed (Ampersend)

PayQL supports all three through the same x402 interface — which wallet pays is just config. Set PAYQL_PAYMENT_MODE:

  • wallet (default, BYO) — sign payments with PAYQL_PRIVATE_KEY. Works in any harness, zero extra deps. This is the floor.

  • harness — don't hold a key. PayQL returns the payable URL + the 402 quote, and your wallet-equipped harness (e.g. an agent with a pay-for-service skill) settles it. The server never touches a key.

  • managed (Ampersend) — pay through an Ampersend-managed smart account, with spend limits, allowlists and auto-top-ups enforced server-side by Ampersend — not just PayQL's local cap. See below.

You don't have to choose globally — the same build does all three depending on config.

Using Ampersend (optional)

Ampersend (by Edge & Node) is a control layer for agent payments built on x402: per-transaction / daily / monthly limits, seller allowlists, auto-top-ups, and self-custodied keys. PayQL integrates it as an opt-in dependency — it is never installed or loaded unless you choose this mode.

  1. Install the SDK (only for this mode):

    npm i @ampersend_ai/ampersend-sdk

  2. Create an agent + smart account in Ampersend and set its spend policy (docs.ampersend.ai). You'll get a smart-account address and a session key.

  3. Configure PayQL:

    PAYQL_PAYMENT_MODE=managed
PAYQL_WALLET_PROVIDER=ampersend
PAYQL_AMPERSEND_SMART_ACCOUNT=0xYourSmartAccount
PAYQL_AMPERSEND_SESSION_KEY=0xYourSessionKey     # or set AMPERSEND_AGENT_ACCOUNT / AMPERSEND_AGENT_KEY
# PAYQL_AMPERSEND_API_URL=...                    # optional; defaults to Ampersend production

Now every paid query is authorized against your Ampersend policy before it's signed — exceed a limit or hit a disallowed payee and Ampersend declines it, which PayQL surfaces as a clear message. Funding/top-ups live in Ampersend, so the BYO "fund your wallet" path doesn't apply.

Built against @ampersend_ai/ampersend-sdk@0.0.28 (pre-1.0). Its createAmpersendHttpClient(...) returns an x402 client that PayQL hands into the very same wrapFetchWithPayment path it uses for BYO. The SDK bundles its own @x402/* (v2); if a future version diverges, pin and re-verify.

Funding (USDC only — no gas)

x402 payments are gasless, so the floor to use PayQL is USDC on Base. To fund the wallet shown by wallet_status:

  • Easiest — Ampersend managed wallet. Use managed mode (Using Ampersend): Ampersend creates the wallet, enforces spend limits, and auto-tops-up USDC — no separate funding step.

  • In a wallet-enabled harness, run its fund/onramp skill and deposit USDC.

  • Buy USDC on Base via any fiat onramp, withdrawing to the address.

  • Already on Base? Send USDC to the address (or swap ETH→USDC, then send).

  • Cross-chain? Bridge USDC to Base via Circle CCTP.

Fiat onramps require KYC, so they're a human setup step — an autonomous agent can't onramp itself. Seed the wallet once (or pre-fund it); the agent then runs on USDC and can self-top-up by swapping. ETH is only needed if the wallet itself does an on-chain swap/bridge/transfer — never to pay a query.

Configuration

Env var

Default

Notes

PAYQL_NETWORK

base

base or base-sepolia

PAYQL_PAYMENT_MODE

wallet if key set, else harness

wallet | harness | managed

PAYQL_PRIVATE_KEY

—

BYO Base wallet key (or X402_PRIVATE_KEY). Never logged.

PAYQL_MAX_USD_PER_QUERY

0.01

Max you'll pay per query. Defaults to the $0.01 rate so you never pay more; a higher quote is refused (preflight shows it first).

PAYQL_REGISTRY_URL

—

Optional free GraphQL endpoint for discovery.

PAYQL_WALLET_PROVIDER

—

Set to ampersend (with PAYQL_PAYMENT_MODE=managed) to pay via an Ampersend-managed wallet.

PAYQL_AMPERSEND_SMART_ACCOUNT / PAYQL_AMPERSEND_SESSION_KEY

—

Ampersend smart-account address + session key (or AMPERSEND_AGENT_ACCOUNT / AMPERSEND_AGENT_KEY). Needs npm i @ampersend_ai/ampersend-sdk.

PAYQL_RPC_URL / PAYQL_GATEWAY_BASE / PAYQL_USDC_ADDRESS / PAYQL_NETWORK_SUBGRAPH_ID

per-network

Advanced overrides.

Security

  • The private key is read from env, used only to sign EIP-3009 authorizations, and never written to logs or tool output. wallet_status returns the address only.

  • The per-query cap (PAYQL_MAX_USD_PER_QUERY) is enforced before any signature is produced.

  • Prefer a dedicated low-balance hot wallet, or harness/managed mode, over a key with significant funds.

Status

Built and verified against the live Graph x402 gateway (Base mainnet): the discover → preflight → price path is exercised end-to-end ($0.01 USDC, exact/eip155:8453, EIP-3009 gasless). The signed-settlement step runs through The Graph's official @x402/fetch client and requires a funded wallet to exercise.

Built on @modelcontextprotocol/sdk, @x402/fetch + @x402/evm, and viem.

License

MIT

Available Tools

5 tools
get_payment_infoGet query priceA

Preflight a subgraph: return the USDC price, asset, payTo and network from the x402 402 challenge WITHOUT paying. Use to estimate cost or to drive a harness-side payment.

ParametersJSON Schema
NameRequiredDescriptionDefault
subgraph_idYesSubgraph ID
queryNoGraphQL query to price (defaults to a minimal _meta probe)

TDQS

A4.2/5.0
Behavior4/5

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

No annotations provided, so description carries full burden. It explicitly states key behavioral traits: preflight action without payment ('WITHOUT paying'). No contradictions, but could mention side effects or error handling.

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

Conciseness5/5

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

Description is a single, well-structured sentence. It front-loads the action and lists return fields efficiently with no wasted words.

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

Completeness4/5

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

Given no output schema, the description lists return fields (USDC price, asset, payTo, network). It covers the primary behavior and inputs but could describe output structure or error scenarios more fully.

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

Parameters3/5

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

Schema description coverage is 100% (both parameters have descriptions), so baseline is 3. The tool description does not add extra parameter semantics beyond the schema.

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

Purpose5/5

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

Description clearly states the tool's purpose: 'Preflight a subgraph' to 'return the USDC price, asset, payTo and network' without payment. It uses specific verbs and specifies the resource, differentiating it from sibling tools like query_subgraph and search_subgraphs.

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

Usage Guidelines4/5

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

Description provides clear usage context: 'Use to estimate cost or to drive a harness-side payment.' It implies when to use but does not explicitly state when not to use or compare with alternative tools.

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

get_subgraph_schemaGet subgraph schema (paid)A

List a subgraph's root queryable entities via GraphQL introspection (a paid x402 query). Use to learn what's queryable before composing a real query.

ParametersJSON Schema
NameRequiredDescriptionDefault
subgraph_idYesSubgraph ID

TDQS

A4.2/5.0
Behavior4/5

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

No annotations are provided, so the description carries the full burden. It discloses that the query is paid (x402) and reactive, indicating no side effects since it's a read-only introspection. It does not mention rate limits or data volume, but the scope is limited to root entities.

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

Conciseness5/5

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

The description is two sentences long, with no redundant wording. The first sentence states the core action and paid nature, and the second sentence gives usage guidance. Every word earns its place.

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

Completeness4/5

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

Given the tool has a single parameter, no output schema, and no annotations, the description covers the necessary context: what it does, when to use it, and the cost implication. It could briefly mention the output format (GraphQL schema) but is sufficiently complete for its simplicity.

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

Parameters3/5

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

With 100% schema description coverage, the baseline is 3. The sole parameter 'subgraph_id' is described in the schema as 'Subgraph ID', and the description adds no additional meaning or format guidance. The description does not explain how to obtain or format the ID.

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

Purpose5/5

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

The description clearly states the tool lists a subgraph's root queryable entities via GraphQL introspection, with a specific verb ('list') and resource ('subgraph's root queryable entities'). It distinguishes from sibling tools like query_subgraph (which executes queries) and search_subgraphs (searching), making the purpose unambiguous.

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

Usage Guidelines4/5

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

The description advises using the tool 'before composing a real query', indicating the appropriate context. It mentions it's a 'paid x402 query', alerting users to cost. However, it does not explicitly state when not to use it or provide alternative tools for similar tasks.

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

query_subgraphQuery a subgraph (paid)A

Run a GraphQL query against a subgraph on The Graph, paying per query in USDC over x402 — gasless and keyless. Returns the data plus a payment receipt (tx hash + amount). Respects the per-query spend cap and returns a fund-wallet message if balance is insufficient.

ParametersJSON Schema
NameRequiredDescriptionDefault
subgraph_idYesSubgraph ID (from search_subgraphs)
queryYesGraphQL query
variablesNoOptional GraphQL variables

TDQS

A4.2/5.0
Behavior4/5

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

No annotations are provided, so the description carries full burden. It discloses payment via x402, returns data plus receipt, respects spend cap, and returns fund-wallet message on insufficient balance. This is good transparency for a paid tool.

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

Conciseness5/5

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

Two sentences, front-loaded with action and key details. No redundancy or waste.

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

Completeness4/5

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

Given no output schema, the description covers return values (data plus payment receipt). It provides enough context for an agent to understand the tool's role among siblings. Could be slightly improved by noting that the receipt includes tx hash and amount.

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

Parameters3/5

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

Schema coverage is 100%, so baseline is 3. The description adds payment context but does not elaborate on parameter usage beyond what the schema provides. The subgraph_id description references search_subgraphs, which is helpful.

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

Purpose5/5

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

The description clearly states the tool runs a GraphQL query against a subgraph on The Graph with payment. It distinguishes itself from siblings like search_subgraphs and get_subgraph_schema by specifying the action (query vs search/schema) and the payment mechanism.

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

Usage Guidelines4/5

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

The description implies when to use (for paid queries against subgraphs) and mentions conditions like spend cap and balance insufficient behavior. However, it does not explicitly contrast with sibling tools or state when not to use it, e.g., for schema retrieval use get_subgraph_schema.

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

search_subgraphsSearch subgraphsA

Find live subgraphs on The Graph by keyword/protocol, ranked by on-chain curation signal (a popularity proxy). Use this to pick a subgraph_id before querying. By default this runs a tiny PAID x402 query against The Graph network subgraph; set PAYQL_REGISTRY_URL to use a free discovery source.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesProtocol or keyword, e.g. 'uniswap v3', 'aave', 'ens'
firstNoMax results (default 10)

TDQS

A4.3/5.0
Behavior4/5

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

Discloses default behavior (tiny PAID x402 query) and config alternative (PAYQL_REGISTRY_URL for free source). No annotations exist, so description carries the burden well.

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

Conciseness5/5

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

Two efficient sentences: first defines purpose, second adds critical usage context. No fluff.

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

Completeness3/5

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

No output schema; description mentions ranking but not specific return fields. For a search tool, more detail on result structure would improve completeness.

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

Parameters4/5

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

Schema coverage 100%, description adds meaning like 'ranked by on-chain curation signal' and default for 'first'. Adds value beyond schema.

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

Purpose5/5

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

The description uses specific verb 'find' and resource 'live subgraphs', mentions ranking by curation signal, and distinguishes from siblings like query_subgraph.

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

Usage Guidelines4/5

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

States 'Use this to pick a subgraph_id before querying', providing clear context. Does not explicitly list when not to use or compare to siblings, but implication is clear.

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

wallet_statusWallet & payment statusA

Report the payment mode, wallet address, USDC/ETH balance on Base, the per-query spend cap and funding instructions. Never reveals the private key.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior4/5

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

The description explicitly states that the tool never reveals the private key, addressing a critical security concern. Since no annotations are present, this behavioral disclosure is valuable. However, it does not explicitly state that the tool is read-only or idempotent, which would further improve transparency.

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

Conciseness5/5

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

The description is a single sentence that front-loads all key information: the reported items and the security guarantee. Every phrase adds value, with no redundancy or vague language. It is optimally concise.

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

Completeness5/5

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

Given the lack of parameters and output schema, the description provides a complete picture of the tool's output. It covers all relevant details (payment mode, wallet address, balances, spend cap, funding instructions) and the security constraint. No additional context is needed for an agent to understand its use.

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

Parameters5/5

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

The input schema has zero parameters, and the description provides full coverage of what the tool returns. This adds meaning beyond the empty schema by listing the exact fields reported. The baseline for zero parameters is 4, and the description's list of fields justifies a higher score.

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

Purpose5/5

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

The description clearly states the tool reports specific wallet and payment status information: payment mode, wallet address, USDC/ETH balance, spend cap, and funding instructions. The verb 'report' and the listed items precisely define the tool's functionality, distinguishing it from sibling tools like 'get_payment_info' which may focus on payment info only.

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

Usage Guidelines2/5

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

No usage guidelines are provided. The description does not advise when to use this tool over siblings such as 'get_payment_info', nor does it mention prerequisites or context. The agent receives no guidance on when this tool is appropriate.

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.1.0
    • First observedget_payment_info
    • First observedget_subgraph_schema
    • First observedquery_subgraph
    • First observedsearch_subgraphs
    • First observedwallet_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a distinct purpose: preflight cost estimation, schema introspection, actual query execution, subgraph search, and wallet status. No overlap or ambiguity.

Naming Consistency4/5

Most tools follow a clear verb_noun pattern (get_payment_info, get_subgraph_schema, query_subgraph, search_subgraphs). wallet_status deviates slightly but remains clear and consistent in style.

Tool Count5/5

Five tools cover the essential operations for a payment-based subgraph query service: preflight, schema, query, search, and wallet management. The count is well-scoped without unnecessary tools.

Completeness4/5

The tool set covers the core workflow: discovery, schema exploration, cost estimation, querying, and wallet status. A minor gap is the lack of a direct funding tool, but the query tool handles insufficient balance by returning funding instructions.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers