Read-only analytics on x402 agent payments and ERC-8004 agent identity, with SQL.
The last two health checks of this connector failed. If this server requires authentication, missing or expired test credentials may be the cause. A test profile lets Glama authenticate for health checks and discover tools; it is separate from your personal connections.
If you are the author, claim ownership, then add or update a test profile under Admin → Test Profile.
Scored across 17 tools
Most tools map to clearly distinct resources (account, graph, leaderboard, facilitators, capabilities, wallet-scoped settlements), but list_flows and list_transactions both return newest-first settlement rows with identical per-row decoration and near-synonymous descriptions ('newest settlements across every indexed chain' vs 'every indexed settlement'), so an agent must guess which to call. get_agent and get_merchant are the same response shape split only by role, which is documented but still one tool's worth of overlap. The capability triple (list_capabilities / get_capability / recommend_capability_offers) is well separated.
Consistent snake_case verb_noun pattern throughout (get_*, list_*, run_sql, recommend_capability_offers), with no mixed casing or vague catch-all verbs. The one wart is get_capability, which wraps /v0/unified/{slug} market data rather than being the singular counterpart of list_capabilities, so the name slightly misdirects about what it returns.
17 tools is toward the heavy end but each mirrors a real endpoint with a distinct job, and a read-only index API of this scope justifies the breadth. It could still be trimmed: get_agent/get_merchant are one tool with a role parameter, and list_flows/list_transactions are one feed with a confidence filter.
The read-only surface is broadly covered: account/pricing, wallets, agents, merchants, settlements, graph, leaderboard, feedback, facilitators, service catalog, capabilities, recommendations, and SQL. The notable gaps are single-record lookups — there is no get_service by id and no fetch of one settlement/transaction by hash — so agents must page through list tools to resolve an individual record.
Who the credential in front of this request resolves to, which of the two paid lanes it would take, what it has left to spend, and the price of every route on both lanes. Unmetered and answerable WITHOUT a key: checking your balance must never cost a unit and must never be the thing that fails. A caller with no key gets a real answer (tier: anonymous, lane: x402, the full price list), not a 401, so both prices can be compared before committing to either. An unrecognised key also answers 200, with key_recognised: false — this is the endpoint you reach for when your key is the thing that is broken, so it must work then.
Wraps GET /v0/account. Access: no API key required.
Returns:
authenticated: Whether a credential was accepted.
key_present: Whether a credential was sent at all.
key_recognised: Whether it resolved, or NULL when none was sent — three-valued, because "no key" and "a key that did not resolve" need different fixes and one false for both would conflate them.
tier: anonymous, trial, oauth, or the organization key tier.
plan: The organization's plan key, or null when there is no organization.
lane: Which lane this caller would take on a metered route, so it can be PREDICTED rather than discovered by being refused: credit draws down Query Units, x402 pays per call, invalid_key resolves to nothing, no_account is a caller with no organisation behind it on the MCP surface, where there is no x402 door, and upgrade_required is that same surface reached by a caller that HAS an organisation whose plan excludes the route. The last two were one value until a signed-in connection with an organisation and a balance was told it had no account behind it.
organisation: Id and display name, or null. Named so an operator with several accounts knows which one to top up.
balance: Units available and the low-balance threshold, or NULL with a balance_note saying why there is no balance to report — an organizationless caller has none, which is not the same as having zero. low_balance is already computed here so a client does not have to know the threshold to apply it.
metered_routes: Every route with what one call costs on each lane: qu on the credit lane, x402_usd on the payment lane. Routes that cost nothing are listed AT ZERO rather than omitted, because a caller cannot tell "free" from "not thought about" by absence. runSql's qu is its MINIMUM — a query is priced by the time it takes, and sql_tiers gives the ceilings.
balance_note: Present only when balance is null, saying WHICH kind of nothing it is: no credential, one that did not resolve, a trial key that holds no balance by design, or an organization row that could not be read. A null balance is never a zero.
sql_tiers: What one run_sql call may cost, which is no longer one number: a query is priced by the time it takes, at one Query Unit per started five seconds with a floor of one. Each tier gives its timeout_seconds, its max_qu (what is HELD for the call and the most it can cost), its own rate limit, and two separate booleans — allowed is whether this caller's plan may buy it, available is whether this deployment can serve it at all. They are separate because "upgrade your plan" and "report a misconfiguration" are different things to go and do, and note says which applies.
top_up_url: Org-scoped deep link to the top-up page, or the plans page for a caller with no organization.
as_of: When this answer was assembled.
summary: One sentence saying what this lane means, for a human reading it in an agent transcript.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only declare readOnly/openWorld/non-destructive; the description goes well beyond that by promising an unmetered call that never costs a unit, always returns 200 rather than 401 for missing or unrecognised keys, and explains the three-valued key_recognised and the null-vs-zero balance distinction. These are exactly the operational traits an agent cannot infer from structured fields, and nothing contradicts readOnlyHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The lead sentence is well front-loaded and the Returns block is organized field-by-field, but the total length is excessive and carries editorial design-history that does not help an agent act — notably the changelog aside about 'the last two were one value until a signed-in connection…' and the recurring justifications of null-vs-zero. Roughly a third of the text is rationale rather than instructions, so it is structured but not tight.
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, documenting return values is squarely the description's job, and it does so exhaustively: every field of the response is enumerated with its meaning, its null cases, and its enum values for tier, lane, and sql_tiers. An agent can parse the response and branch on lane without any other source.
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 4 baseline applies and there is no parameter semantics to add. The description correctly spends no space on input arguments and instead devotes itself to the response shape, which is the right allocation.
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 opening sentence names a concrete verb set (resolves identity, selects lane, reports balance and prices) against a specific resource — the credential in front of the request — and verb 'wraps GET /v0/account' anchors it. Among siblings like get_agent, get_capability, and list_wallets, no other tool claims to report caller identity plus entitlement plus pricing, so the agent can route here unambiguously.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a strong when-to-use: check entitlement and price before committing to a lane, and specifically reach for it when your own key is the thing that is broken. It also states the no-key case is valid, which prevents the agent from self-censoring the call. What it lacks is an explicit contrast against siblings (e.g. why get_account rather than get_agent for identity), so the routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One wallet in its paying role: its resolved identity and its own settlement aggregates. Every figure is that wallet's own — there are no site-wide totals on this endpoint.
Wraps GET /v0/agents/{wallet}. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
wallet: The wallet queried, lowercased.
role: The role it was queried in: agent or merchant.
coverage: Read this first. known false means the index has never observed this address, so every figure below is a zero meaning "not observed" — not "observed to be nothing". Also first_seen, last_seen, settlements_scanned, scan_truncated and scan_cap.
entities: Resolved identity rows: display name, ENS, ERC-8004 card, role, first and last seen.
erc8004_agents: ERC-8004 registrations whose on-chain agentWallet is this address.
aggregates: That wallet's own totals: inbound/outbound USD and counts, distinct counterparties, chain split. basis says what they were computed over — index_rollup is the whole history, scanned_settlements is the capped scan and is a floor when coverage.scan_truncated is set. distinct_counterparties excludes the wallet itself on both bases. chain_split is the exception and carries its own chain_split_basis: the rollup is keyed by wallet and holds no chain dimension, so that split is ALWAYS the scan and is capped with it, whatever the object-level basis says.
data_quality: The risk annotation. Route on verdict, not on note. verdict is one of unobserved (never seen — nothing assessed), patterns_detected, no_patterns_detected, or insufficient_evidence — the last meaning the address WAS observed, nothing fired, and not enough of its history was examined for that to rule anything out. checks carries every check with its threshold, what was observed, its own basis, and conclusive: a check that FIRED is always conclusive (a pattern seen in a sample happened), a check that did not fire on a truncated scan is not. note says the same thing in a sentence and is derived from the two.
recent: A slice of its activity, recent_limit rows (default 5). Each row also carries is_self_payment (payer = payee, annotated rather than only excluded — a third of the feed can be self-payment) and evidence: { verified, method, probability, tier }. verified is THREE-VALUED — true a named facilitator relayed it, false examined with no EIP-3009 marker, and null gasless and authorized but NOT ESTABLISHED as x402, which is not the same as disproven. tier is proven | probable | unproven | not_x402 | ungraded.
| Name | Required | Description | Default |
|---|---|---|---|
| wallet | Yes | An EVM address (`0x` + 40 hex digits; case-insensitive, lowercased before lookup) or a Solana address (base58; case-sensitive, used exactly as given). An address the index has not observed answers `coverage.known: false`, not zeros. | |
| recent_limit | No | Settlement rows to embed in the profile. 0 omits them. Default 5 — this was an unbounded 25, which is most of the payload on a surface where a response is billed as context tokens. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, non-destructive, openWorld), and the description still adds material context: the API-key auth scheme, scan truncation making aggregates a floor, chain_split always being scan-based regardless of object-level basis, and the three-valued `verified` field where null means not-established rather than disproven. That is real behavioral disclosure beyond structured fields, with only minor gaps (no rate limits or payload size limits).
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?
Long, but front-loaded with purpose, endpoint, and auth, then organized into a bulleted Returns block that maps to a response with no output schema. The density is justified, though a few editorial asides ('which is most of the payload on a surface where a response is billed as context tokens') could be trimmed without loss.
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 carries the full burden of explaining returns, and it does so thoroughly: coverage semantics, entity resolution, ERC-8004 linkage, aggregate bases, data_quality verdict routing, and the recent-activity evidence model. An agent has everything needed to call the tool and to interpret each field 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 coverage is 100%, so both parameters are already documented thoroughly, including the EVM/Solana address formats and recent_limit's 0-to-50 range. The description echoes the default of 5 and reinforces the coverage.known:false behavior, but adds little the schema does not already say; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: one wallet's resolved identity plus its own settlement aggregates, wrapping GET /v0/agents/{wallet}. It also pre-empts confusion with the many list_* siblings by declaring 'there are no site-wide totals on this endpoint,' so an agent knows this is a single-wallet lookup rather than a roster or leaderboard call.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage guidance is interpretive rather than routing: 'Read this first' on coverage and 'Route on verdict, not on note' tell the agent how to consume the payload. It never explicitly says when to choose this over get_account, get_merchant, or list_entity_settlements, so the agent must infer sibling boundaries from names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every indexed endpoint that does this job, with the market's going rate. price.spot is the call-WEIGHTED price, not the median — a median counts one wallet's forty near-identical listings as forty votes for its price. Check price.spot_basis: median means no offer reported any calls and the figure is a fallback, which does not mean the same thing as a market rate. truncated: true means the offer list is a floor.
Wraps GET /v0/unified/{slug}. Access: no API key required.
Returns:
capability: The registry entry: the job, its priced unit, and its canonical request/response.
price: Going rate (spot), its basis, and the min / p25 / median / p75 / max spread.
stats: How many offers, distinct providers, distinct hosts, and how many were answering when last probed.
models: For inference capabilities: which model families are sold here, and by how many providers.
offers: Each endpoint, its listed price, its index against spot (100 = the going rate), and its reported 30-day demand.
truncated: True when the candidate read hit its cap, so the offer list is a floor rather than the whole market.
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | Capability slug, from `/v0/unified`. | |
| limit | No | Rows to return. Clamped to 200; values outside the range are clamped, not rejected. | |
| probable | No | Include endpoints the matcher was not confident about. Off by default: grouping two endpoints that do different jobs invents a cheaper competitor that does not exist. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the read-only, non-destructive, open-world profile. The description adds useful behavioral context beyond them: the underlying endpoint (`GET /v0/unified/{slug}`), that no API key is required, and that `truncated: true` means the offer list is a floor rather than the complete market.
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 front-loaded with the core purpose and then uses a structured 'Returns' section. It is somewhat dense, especially around price semantics, but the explanatory sentences about spot basis and truncation earn their place given there is no 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?
Because there is no output schema, the description carries the full burden of explaining return values, and it does so thoroughly: capability, price fields, stats, models, offers, and truncation are all defined. Combined with annotations covering safety and the description covering auth and endpoint details, an agent has what it needs to call and interpret the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents `slug`, `limit`, and `probable` thoroughly. The description does not add meaning to those parameters; it focuses on return fields and pricing semantics instead, making the baseline 3 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?
The description clearly states the resource: every indexed endpoint offering a given capability, with market pricing. It distinguishes detail from listing implicitly through 'this job' and the singular slug requirement, but it never names `list_capabilities` or `recommend_capability_offers` as alternatives.
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?
There is no explicit when-to-use guidance, no when-not-to-use conditions, and no named alternatives among the sibling tools. The description explains how to interpret pricing fields rather than guiding tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Entities as nodes and settlements aggregated into edges, over a bounded window. Two window forms, and exactly one may be sent: window=N is a row count running to the live tip (briefly cacheable); days=N covers whole UTC days only, excluding today, so an answer is stable for the day. Use days for anything an agent will cache. Self-payments are excluded from BOTH edges and node totals and counted in meta.excluded, so sum(node.window_usd) is exactly twice sum(edge.usd).
Wraps GET /v0/graph. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
applied: Every parameter as APPLIED, not as requested — both windows, the edge cap, the facilitator caps, the chain, the filters. Read this rather than assuming the request was honoured verbatim. days and window can BOTH be non-null: a wallet-focused day window is read row by row, so a row cap applies inside the declared range and complete says whether it bit.
complete: Whether the declared window was read in full. False means a row cap stopped the read inside the range — the response then covers the newest applied.window settlements in it, not the whole of it, and meta.warnings says so. Only ?days= with ?wallet= can be false.
days: The whole-UTC-day window applied, or null on the window=N path.
since: Inclusive start of the day window, or null on the window=N path.
until: Exclusive end of the day window (midnight today), or null on the window=N path.
since_day: The since bound as a UTC date, or null.
until_day: The until bound as a UTC date, or null.
mode: daily when the answer came from the per-day rollup, which covers the window exactly; raw when it was folded from settlement rows.
bucket: What one source row represented: day under mode: daily, settlement under raw.
truncated: True when the edge cap dropped edges the window contained.
nodes: One entry per wallet: role, display name, ENS, and its window totals.
edges: Aggregated payer→payee pairs with volume and count.
series: Per-day bucket totals across the window. null on the window=N path, which is a row count with no day grain to bucket into.
facilitators: Relayers seen in the window, largest first and capped to applied.facilitators. usd/count are the relayer's own window totals; links name only wallets present in nodes, capped to applied.facilitator_links, with links_total and links_truncated beside them.
window: How the window was read: rows requested, fetched and used.
meta: The chain served, as_of, and excluded — the self-payments, low-confidence rows, over-cap edges and over-cap facilitators the window held but the graph does not show, so node and edge totals can be reconciled. below_min_usd is null when min_usd was sent: that filter runs at read time, so its exclusions never reach this response and cannot be counted.
| Name | Required | Description | Default |
|---|---|---|---|
| via | No | Restrict to settlements relayed by this facilitator key or wallet. | |
| days | No | Whole UTC days, excluding today, honoured exactly: `days=1` is one day. Mutually exclusive with `window`. Out of `[1,180]` is refused rather than clamped. | |
| chain | No | CAIP-2 chain id. Defaults to the chain this deployment indexes (`eip155:8453` in production, `eip155:84532` on staging) — the same default every endpoint on this API uses. A chain the index does not carry is refused with 400 listing the supported set, never answered with an empty list. | |
| edges | No | Hard cap on edges returned, highest volume first. Honoured exactly; `truncated` says whether it bit. | |
| wallet | No | Restrict to edges touching this wallet. Must be a well-formed EVM address (case-insensitive) or Solana address (base58, case-sensitive). | |
| window | No | Row count back from the live tip. Mutually exclusive with `days` — sending both is refused with 400, not silently resolved in favour of one. | |
| min_usd | No | Drop settlements below this USD value. | |
| min_probability | No | Minimum x402 confidence, in `[0,1]`. Default 0.5. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds substantial behavioral context beyond the annotations: it states API-key auth requirements, cacheability differences between window forms, stability of whole-UTC-day windows, self-payment exclusion, applied-vs-requested semantics, `complete` semantics, truncation behavior, and how `meta` supports reconciliation. These details materially help an agent predict how the tool behaves and interpret its results.
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 front-loaded with the core concept and then structured into a clear Returns section, which is appropriate given the absence of an output schema. It is still quite long and revisits some window semantics in both the opening and the return-field explanations, so it is not maximally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a complex graph tool with eight parameters and no output schema, the description is complete: it covers purpose, window semantics, auth, key output fields, truncation, exclusions, and reconciliation caveats. An agent has enough information to call it correctly and interpret the response without additional documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the parameters are already well documented, but the description adds operational meaning around choosing `days` for cacheable answers versus `window=N` for a row count to the live tip. It also reinforces mutual exclusivity and explains how a row cap can apply inside a day window, which goes 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 clearly states that it returns a payment graph: entities as nodes and aggregated settlements as payer→payee edges over a bounded window, and it identifies the wrapped endpoint GET /v0/graph. It is specific about the resource and scope, but it does not explicitly differentiate itself from sibling tools such as list_entity_settlements or list_flows.
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?
Guidance is mostly implied by the graph-oriented purpose and by the explicit 'Use `days` for anything an agent will cache' note, which helps choose between the two window modes. However, it does not say when to use get_graph instead of sibling tools like list_entity_settlements, list_flows, or run_sql.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Agents ordered by the ERC-8004 reputation score, which is the on-chain registry's number and not a Roundhouse rating. Unscored agents sort last rather than dropping out, so a board where nothing has been scored still comes back looking ordered — check meta.page_scored_agents, which is how many rows on the page carry a score at all. Zero means the order is the agent_id tie-break and nothing more. It pages by offset rather than a cursor, because a rank is a position and score is nullable — a keyset has nothing stable to compare against across the scored/unscored boundary.
Wraps GET /v0/leaderboard. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
leaderboard: Agent rows in score order, unscored last.
next_offset: Offset for the next page, or null.
meta: The chain served, as_of, and page_scored_agents — rows on this page with a non-null score. A no_agent_on_this_page_has_a_score warning when that is zero.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return. Clamped to 100; values outside the range are clamped, not rejected. | |
| offset | No | Rows to skip. Use the returned `next_offset`. | |
| include_spam | No | Set to `1` to include agents with no feedback, which are hidden by default. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/non-destructive/open-world profile, and the description adds real context beyond them: API-key auth requirement, the tie-break-by-agent_id fallback, the warning code emitted when no row is scored, and why cursor paging is impossible here. These are exactly the traps an agent would otherwise hit.
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, followed by the unscored-sorting caveat, then the paging rationale, then transport/auth and return shape. Dense but each sentence carries information; only the 'Wraps GET /v0/leaderboard' line is near-redundant with the endpoint framing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating the return fields (leaderboard, next_offset, meta, page_scored_agents, the no_agent_on_this_page_has_a_score warning). Auth, paging, ordering edge cases, and defaults are all covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents limit, offset, and include_spam. The description adds reasoning the schema lacks — why offset is used instead of a keyset cursor and what meta fields accompany the page — which meaningfully informs how offset should be driven.
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 pairing (agents ordered by ERC-8004 reputation score) and disambiguates the score's provenance from a 'Roundhouse rating'. It never names list_agents as the unordered alternative, so the sibling boundary is only implied by the emphasis on ordering.
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 clear operational context: paging is by offset because ranks are positions across a nullable score, and the caller should inspect meta.page_scored_agents because an all-unscored board can masquerade as a ranked one. No explicit when-not or named alternative tool, which keeps it below a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The same shape as /agents/{wallet}, for a wallet in its receiving role.
Wraps GET /v0/merchants/{wallet}. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
wallet: The wallet queried, lowercased.
role: The role it was queried in: agent or merchant.
coverage: Read this first. known false means the index has never observed this address, so every figure below is a zero meaning "not observed" — not "observed to be nothing". Also first_seen, last_seen, settlements_scanned, scan_truncated and scan_cap.
entities: Resolved identity rows: display name, ENS, ERC-8004 card, role, first and last seen.
erc8004_agents: ERC-8004 registrations whose on-chain agentWallet is this address.
aggregates: That wallet's own totals: inbound/outbound USD and counts, distinct counterparties, chain split. basis says what they were computed over — index_rollup is the whole history, scanned_settlements is the capped scan and is a floor when coverage.scan_truncated is set. distinct_counterparties excludes the wallet itself on both bases. chain_split is the exception and carries its own chain_split_basis: the rollup is keyed by wallet and holds no chain dimension, so that split is ALWAYS the scan and is capped with it, whatever the object-level basis says.
data_quality: The risk annotation. Route on verdict, not on note. verdict is one of unobserved (never seen — nothing assessed), patterns_detected, no_patterns_detected, or insufficient_evidence — the last meaning the address WAS observed, nothing fired, and not enough of its history was examined for that to rule anything out. checks carries every check with its threshold, what was observed, its own basis, and conclusive: a check that FIRED is always conclusive (a pattern seen in a sample happened), a check that did not fire on a truncated scan is not. note says the same thing in a sentence and is derived from the two.
recent: A slice of its activity, recent_limit rows (default 5). Each row also carries is_self_payment (payer = payee, annotated rather than only excluded — a third of the feed can be self-payment) and evidence: { verified, method, probability, tier }. verified is THREE-VALUED — true a named facilitator relayed it, false examined with no EIP-3009 marker, and null gasless and authorized but NOT ESTABLISHED as x402, which is not the same as disproven. tier is proven | probable | unproven | not_x402 | ungraded.
| Name | Required | Description | Default |
|---|---|---|---|
| wallet | Yes | An EVM address (`0x` + 40 hex digits; case-insensitive, lowercased before lookup) or a Solana address (base58; case-sensitive, used exactly as given). An address the index has not observed answers `coverage.known: false`, not zeros. | |
| recent_limit | No | Settlement rows to embed in the profile. 0 omits them. Default 5 — this was an unbounded 25, which is most of the payload on a surface where a response is billed as context tokens. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the read-only/open-world/no-destructive profile, and the description layers on far more: auth scheme, the upstream route, the meaning of `coverage.known: false`, truncation semantics with `scan_truncated`/`scan_cap`, and the basis mismatch where `chain_split` is always scan-derived regardless of object-level `basis`. It also flags the three-valued `verified` field and the self-payment annotation, which are exactly the traps that cause misreading.
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?
Long (well over 300 words) but organized into labeled sections that front-load the sibling distinction ahead of the return-value walkthrough. Nearly every clause carries non-obvious semantics; a few asides ('a third of the feed can be self-payment', 'note says the same thing in a sentence') are editorial padding that could be trimmed.
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 carries the full burden of describing the return shape, and it does so field by field — coverage, entities, erc8004_agents, aggregates with basis caveats, data_quality verdict enumeration, and recent-row evidence tiers. Nothing an agent needs to interpret the payload 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 both parameters are already fully documented, including the EVM-vs-Solana address format and the recent_limit default/bounds rationale. The description only restates `recent_limit` rows (default 5) when describing the `recent` block, adding no syntax or format detail beyond the schema — 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 concrete resource (per-merchant stats and identity) and immediately differentiates it from the sibling get_agent by framing it as the same shape as `/agents/{wallet}` but in the wallet's receiving role, plus names the upstream endpoint. An agent can pick between get_agent and get_merchant without opening either 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?
The `agent` vs `merchant` role framing implies the alternative (get_agent) and when to prefer this one, and access requirements (API key, Bearer rh_live_… / x-api-key) are stated. It also gives consumption-level routing guidance ('Read coverage first', 'Route on verdict, not on note'), but never states an explicit 'use this tool when… / not when…' exclusion clause.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Raw feedback entries from the ReputationRegistry for a single agent id.
Wraps GET /v0/agents/{agentId}/feedback. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
agent_id: The id queried.
chain: The chain the feedback was read from.
feedback: Feedback entries.
meta: The chain served and as_of. On an EMPTY list it also carries dataset_last_written_at, dataset_row_count and any warnings (e.g. endpoints_catalog_stale) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.
| Name | Required | Description | Default |
|---|---|---|---|
| chain | No | CAIP-2 chain id. An agent id is not unique across chains. | |
| limit | No | Rows to return. Clamped to 100; values outside the range are clamped, not rejected. | |
| agentId | Yes | ERC-8004 agent id. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, non-destructive, open-world behavior, and the description goes further by disclosing the auth requirement (Bearer rh_live_… or x-api-key), the wrapped REST endpoint, and — most valuably — that an empty list still carries dataset_last_written_at, dataset_row_count and warnings so a zero is interpretable rather than ambiguous. It does not discuss pagination behavior beyond what the schema shows.
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 purpose, then endpoint, then access, then a Returns list; the multi-section layout is easy to scan. The Returns bullet list is somewhat verbose for a tool without an output schema, but the empty-list caveat earns its space.
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 appropriately enumerates the return fields (agent_id, chain, feedback, meta) and explains the diagnostic meta on empty results. Remaining gaps are minor: nothing on result ordering or pagination beyond the clamped limit parameter.
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 agentId, chain (CAIP-2, agent id not unique across chains) and limit (clamped to 100) are fully documented in the schema. The description adds no parameter-level detail beyond reiterating that chain identifies where feedback was read, 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 and resource (raw feedback entries from the ReputationRegistry) scoped to a single agent id, and names the underlying endpoint (GET /v0/agents/{agentId}/feedback). This clearly separates it from get_agent, which returns the agent record rather than its reputation entries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the scope 'for a single agent id,' but there is no explicit when-to-use/when-not guidance and no routing to alternatives (e.g., get_agent for profile data, or a leaderboard tool for aggregate rankings). An agent must infer the correct tool from the name and purpose line alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Agents read from the on-chain IdentityRegistry, with their registration card and payment wallet. score is the ERC-8004 reputation score derived from on-chain feedback — it is the REGISTRY's number, not a Roundhouse rating, and it is null for every agent no counterparty has left feedback for. Roundhouse publishes no trust score of its own.
Wraps GET /v0/agents. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
agents: Agent rows with identity, wallet and the ERC-8004 score (null where the registry holds no feedback). x402_support is the registration card's own declaration; last_activity_at and activity_status are the observed halves, derived from settlements and feedback.
next_before: Cursor for the next page, or null.
meta: The chain served and as_of. On an EMPTY list it also carries dataset_last_written_at, dataset_row_count and any warnings (e.g. endpoints_catalog_stale) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text search over name and description. | |
| x402 | No | The earlier name for `x402_declared`, kept because it is published and a caller sending it wants the same rows. Prefer `x402_declared`, whose name says what it reads. Sending both uses `x402_declared`. | |
| limit | No | Rows to return. Clamped to 100; values outside the range are clamped, not rejected. | |
| before | No | Opaque cursor from a previous response's `next_before`. It encodes the whole sort key, tiebreaker included, so a page boundary inside a group of rows sharing a timestamp does not skip the rest. Do not parse it or build one by hand. | |
| x402_declared | No | Set to `true` to keep only agents whose own ERC-8004 registration card declares x402 support (`x402Support: true`). This is the agent's CLAIM ABOUT ITSELF, copied out of a document its owner wrote, and it is not evidence of anything: four of five agents on a page of this filter had `last_activity_at: null`, `activity_status: "unknown"` and no feedback — never observed doing anything. It was named `x402` and documented as "observed on-chain x402 payments", which is the one confusion this index exists to prevent. The old name still works and means the same thing. There is no observed equivalent yet: `agents` carries no per-wallet settlement column, and the weekly activity scan that would populate one covers five agents a run against tens of thousands, so a filter built on it would answer "not observed" about agents nobody has looked at. To screen on evidence today, take the `agent_wallet` and call `get_agent` / `list_entity_settlements` with it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this read-only/open-world, and the description adds substantial context beyond them: the Bearer/x-api-key auth requirement, that `score` is the registry's number and null without counterparty feedback, that Roundhouse publishes no trust score, and that an empty list carries warnings like `endpoints_catalog_stale` so a zero isn't misread. It also discloses that `x402_declared` is a self-claim, not observed evidence. This is exactly the kind of caveat annotations can't express.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It's long, but the Returns bullet block and the explicit endpoint/auth lines make it scannable, and most sentences carry real signal (empty-list metadata, cursor guarantees, declared-vs-observed). It loses a point for front-loading the `score` caveat ahead of the basic 'what this lists' statement and for some repetition of schema text about the `x402` alias.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, so the description must cover return values, and it does: `agents` fields, `next_before` cursor behavior, and `meta` including the empty-list extension. Combined with the auth and score caveats, an agent has everything needed to call this and interpret the response 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 coverage is 100% and each parameter is already documented in detail, including the `x402` vs `x402_declared` legacy alias and cursor semantics, so the description's parameter-level value is mostly redundant. The one genuinely additive note is the framing that the declared filter answers a claim rather than an observation. With the schema doing the heavy lifting, baseline 3 is right.
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 the resource ('Agents read from the on-chain IdentityRegistry, with their registration card and payment wallet') and pins down the endpoint ('Wraps GET /v0/agents'), so it's clear this is a paged listing of indexed agents. It distinguishes itself from get_agent by pointing to that sibling for evidence screening. It stops just short of a crisp verb-first opener, leading with score semantics instead of 'List agents'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit routing: to screen on observed evidence, take `agent_wallet` and call `get_agent` / `list_entity_settlements`, and explains why no observed-x402 filter exists here. That's a real alternative-selection rule. It lacks a plain 'use this to browse/search the agent index' statement and any exclusion for cases where get_leaderboard or run_sql would be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every job the catalog is grouped by, with the canonical request and response each provider of that job is mapped onto — which is what lets an agent swap one endpoint for another without changing its code. Static: no market figures here, because each one costs its own catalog walk. Ask /unified/{slug} for a capability's offers and going rate. Send fields=compact when you are only choosing a capability: the full response carries both IO schemas for all of them.
Wraps GET /v0/unified. Access: no API key required.
Returns:
capabilities: Slug, name, group, priced unit and — on fields=full — summary and the canonical input/output fields.
count: How many capabilities the registry defines.
fields: Which shape was served: full or compact.
note: Where the market figures for one capability live.
| Name | Required | Description | Default |
|---|---|---|---|
| fields | No | `compact` returns slug, name, group and unit only — enough to pick a capability, without 34 pairs of IO schemas in the payload. | full |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it as read-only, open-world, and non-destructive, and the description adds useful context: the data is static, no API key is required, and the compact/full choice affects payload size because the full response includes both IO schemas for all capabilities.
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 front-loaded with the core concept and then provides structured return details. It is somewhat verbose, with a few explanatory clauses that could be tightened, but most sentences provide actionable information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one optional parameter, no output schema, and clear annotations, the description is complete: it covers purpose, access requirements, response shape, compact/full behavior, and where to go for market figures.
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 enum is documented, so the schema carries most parameter meaning. The description still adds practical guidance on when `fields=compact` is preferable and what `fields=full` includes, which goes beyond the raw schema definition.
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 that this tool exposes the full capability catalogue: every job the catalog is grouped by, with canonical request/response mappings. It also distinguishes this static catalogue from per-capability offer data available via `/unified/{slug}`.
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 compact form versus the full form, and it explains that market figures are not here and should be fetched from `/unified/{slug}`. This gives the agent clear routing guidance between catalogue inspection and per-capability offer lookup.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Settlements where this wallet is either the payer or the payee, newest first. Walkable deeply in time order: (payer, block_time desc) and (payee, block_time desc) cover it, so page N costs what page 1 does and a wallet's whole history can be paged for velocity or trend.
Wraps GET /v0/entities/{wallet}/settlements. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
wallet: The wallet queried, lowercased.
settlements: Settlement rows, newest first, decorated with resolved display names. Each row also carries is_self_payment (payer = payee, annotated rather than only excluded — a third of the feed can be self-payment) and evidence: { verified, method, probability, tier }. verified is THREE-VALUED — true a named facilitator relayed it, false examined with no EIP-3009 marker, and null gasless and authorized but NOT ESTABLISHED as x402, which is not the same as disproven. tier is proven | probable | unproven | not_x402 | ungraded.
next_before: Cursor for the next page, or null.
meta: The chain served and as_of. On a non-empty page meta also carries page_self_payments, page_self_payment_usd, page_gross_usd and page_organic_usd. All four are THIS PAGE only, as the names say: they are not site-wide figures and summing them across pages is not a total.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return. Clamped to 100; values outside the range are clamped, not rejected. | |
| before | No | Opaque cursor from a previous response's `next_before`. It encodes the whole sort key, tiebreaker included, so a page boundary inside a group of rows sharing a timestamp does not skip the rest. Do not parse it or build one by hand. | |
| wallet | Yes | An EVM address (`0x` + 40 hex digits; case-insensitive, lowercased before lookup) or a Solana address (base58; case-sensitive, used exactly as given). An address the index has not observed answers `coverage.known: false`, not zeros. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnly/openWorld), it discloses the auth requirement (Bearer API key), pagination cost, the three-valued `verified` semantics, the `tier` enum, and the critical caveat that `page_*` meta fields are per-page and not summable across pages. This is exactly the kind of behavioral context an agent can't infer from structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It's front-loaded with the purpose and organized into a Returns section, and every claim is substantive. The 'Walkable deeply in time order' sentence is a bit dense and slightly overwrought, keeping it just under top marks.
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 and read-only annotations covered, the description fully carries the burden: it documents the return fields, the ambiguous three-valued `verified`, and the per-page aggregation trap. An agent has everything needed to call and interpret it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all three parameters are already documented, including clamping behavior and the opaque cursor. The description's paging-cost remark adds marginal context but doesn't elaborate parameter syntax beyond the schema, 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?
The opening sentence states a specific resource and disambiguates scope: settlements where the wallet is payer OR payee, ordered newest first. This clearly separates it from sibling tools like list_transactions and list_flows.
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 explains that the underlying indexes enable deep sequential paging, so an agent knows it can walk a wallet's whole history for velocity or trend analysis, and it implies this is the right tool for per-wallet settlement history. It doesn't explicitly name an alternative (e.g. list_transactions) or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The facilitators seen relaying settlements, with their known relayer wallets. Paged: this used to return up to 200 rows unpaged, most of their columns null. Null-valued columns are omitted from each row.
Wraps GET /v0/facilitators. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
chain: The chain served — this deployment's default when none was named.
facilitators: Facilitator rows, busiest first. Null-valued fields are omitted.
next_offset: Offset for the next page, or null.
meta: The chain served and as_of. On an EMPTY list it also carries dataset_last_written_at, dataset_row_count and any warnings (e.g. endpoints_catalog_stale) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.
| Name | Required | Description | Default |
|---|---|---|---|
| chain | No | CAIP-2 chain id. Defaults to the chain this deployment indexes (`eip155:8453` in production, `eip155:84532` on staging) — the same default every endpoint on this API uses. A chain the index does not carry is refused with 400 listing the supported set, never answered with an empty list. | |
| limit | No | Rows to return. Clamped to 200; values outside the range are clamped, not rejected. | |
| offset | No | Rows to skip. Use the returned `next_offset`. | |
| enriched_only | No | Keep only relayers whose nonce and gas balance have been read. A row without `enriched_at` has nothing populated but its address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnly/openWorld/non-destructive); the description adds real operational context beyond them: API-key auth requirement, the underlying GET endpoint, pagination via next_offset, omission of null columns, 400 refusal (not empty list) for unsupported chains, and how to read an empty result via meta warnings.
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 core identity and paging change are front-loaded and the Returns block is justified by the absence of an output schema. There is minor redundancy — null-column omission is stated twice — and the historical 'used to return up to 200 rows' note is filler, though it does motivate the paging contract.
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 carries the return shape well (chain, facilitators, next_offset, meta, including empty-list diagnostics) plus auth and error semantics. It stops short of enumerating what fields a facilitator row actually contains (address, enriched_at, nonce, gas balance surface only obliquely via parameter text).
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 all four parameters are already documented in depth (clamping behavior, default chain ids, next_offset guidance). The description adds the paging contract at a high level but no parameter meaning beyond what the schema already carries — 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 resource and scope: facilitators/relayers seen settling, with their known relayer wallets, per chain. The title and first sentence together make it unmistakably distinct from siblings like list_wallets, list_agents, and list_entity_settlements, which cover different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied — you call this to enumerate relayers for a chain — and the `enriched_only` parameter description hints at a 'only fully-read rows' use case. But the description never says when to prefer this over a sibling (e.g. list_wallets or run_sql) or when not to call it; routing 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.
The newest settlements across every indexed chain, payer to payee. This is the same feed the /flows page renders.
Wraps GET /v0/flows. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
flows: Settlement rows, newest first, decorated with resolved display names. Each row also carries is_self_payment (payer = payee, annotated rather than only excluded — a third of the feed can be self-payment) and evidence: { verified, method, probability, tier }. verified is THREE-VALUED — true a named facilitator relayed it, false examined with no EIP-3009 marker, and null gasless and authorized but NOT ESTABLISHED as x402, which is not the same as disproven. tier is proven | probable | unproven | not_x402 | ungraded.
next_before: Cursor for the next page, or null at the end of the list.
meta: The chain served and as_of. On a non-empty page meta also carries page_self_payments, page_self_payment_usd, page_gross_usd and page_organic_usd. All four are THIS PAGE only, as the names say: they are not site-wide figures and summing them across pages is not a total. On an EMPTY list it instead carries dataset_last_written_at, dataset_row_count and any warnings.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return. Clamped to 100; values outside the range are clamped, not rejected. | |
| before | No | Opaque cursor from a previous response's `next_before`. It encodes the whole sort key, tiebreaker included, so a page boundary inside a group of rows sharing a timestamp does not skip the rest. Do not parse it or build one by hand. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the read-only/open-world safety profile; the description adds substantial behavioral detail on top: exact auth header forms, the three-valued `verified` flag with explicit guidance that `null` is not the same as disproven, the `tier` vocabulary, and the warning that page-level USD metrics must not be summed across pages. This is precisely the kind of context 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, then access, then a structured Returns block with bullets — easy to scan. It runs long, but the length is largely earned because there is no output schema to carry the return-shape detail; only minor phrasing ('decorated with resolved display names') is expendable.
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 does the full job: it documents each return field, the three-valued evidence semantics, page-scoped vs site-wide metric caveats, and the distinct empty-list `meta` shape. An agent can interpret every response shape, including the empty and end-of-list cases, without further information.
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's own descriptions for `limit` and `before` are already richer than anything the tool description adds about them. The description's cursor note ('Cursor for the next page, or null at the end') restates the schema rather than extending it, 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 resource and scope: 'newest settlements across every indexed chain, payer to payee', plus the endpoint it wraps (GET /v0/flows) and the UI surface it mirrors. That implicitly contrasts with entity-scoped siblings like list_entity_settlements, but no sibling is named, so the differentiation is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied rather than stated: 'the newest settlements' plus 'the same feed the /flows page renders' tells the agent this is the live global feed, and the API-key requirement is spelled out. But nothing says when to choose this over list_transactions or list_entity_settlements, and there are no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The x402 service catalog, ordered by observed 30-day call volume. A listing is a claim; the observed columns are evidence — prefer is_live with non-zero l30_unique_payers. Note the path stays /v0/endpoints although the human page moved to /services; renaming it would break published integrations.
Wraps GET /v0/endpoints. Access: no API key required.
Returns:
endpoints: Catalog rows with price, network, payTo, liveness and observed demand.
next_offset: Offset for the next page, or null when this page was the last.
meta: The chain served and as_of. On an EMPTY list it also carries dataset_last_written_at, dataset_row_count and any warnings (e.g. endpoints_catalog_stale) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.
| Name | Required | Description | Default |
|---|---|---|---|
| q | No | Free-text search over service name, description and resource URL. | |
| limit | No | Rows to return. Clamped to 200; values outside the range are clamped, not rejected. | |
| fields | No | `compact` returns name, resource, price, network, payTo and liveness only — no description, icon or tags — which is roughly a third of the payload. | full |
| offset | No | Rows to skip. Use the returned `next_offset`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations it discloses auth requirements (no API key), pagination contract via next_offset, and a genuinely non-obvious edge case: on an empty list, meta carries dataset_last_written_at, dataset_row_count and warnings such as endpoints_catalog_stale. It also explains the deliberate path quirk (/v0/endpoints vs /services), which an agent might otherwise try to 'fix'. None of this is derivable from the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the resource and ordering, then access, then returns, then an explicit empty-list caveat. Most sentences earn their place; the aside about renaming the path is marginally tangential but useful to an agent that might construct URLs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by enumerating all three return fields, describing pagination termination, and explaining the degenerate empty-result shape. An agent has everything needed to call it and to interpret an empty page 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 all four parameters are already documented with defaults, bounds and the enum meaning. The description adds nothing parameter-specific; it only references next_offset as a return value. Baseline 3 applies, though the schema itself is internally inconsistent (limit maximum 50 vs prose saying 'clamped to 200').
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 opening sentence names a specific resource (the x402 service catalog) and its ordering (30-day call volume), plus the wrapped endpoint GET /v0/endpoints. It is clear what is listed, though it never explicitly contrasts itself with list_capabilities or list_facilitators, which sit close by in the sibling set.
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?
Guidance is about interpreting results ('prefer is_live with non-zero l30_unique_payers', reading a zero as quiet market vs stalled ingest) rather than about when to call this tool versus a sibling. The use case (browsing/searching the service directory) is implied rather than stated with alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every indexed settlement, newest first, filterable by how confidently it is known to be an x402 payment.
Wraps GET /v0/transactions. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
transactions: Settlement rows, newest first. Each row also carries is_self_payment (payer = payee, annotated rather than only excluded — a third of the feed can be self-payment) and evidence: { verified, method, probability, tier }. verified is THREE-VALUED — true a named facilitator relayed it, false examined with no EIP-3009 marker, and null gasless and authorized but NOT ESTABLISHED as x402, which is not the same as disproven. tier is proven | probable | unproven | not_x402 | ungraded.
next_before: Cursor for the next page, or null. Minted from the rows READ, not the rows shown, so exclude_self_payments cannot end the walk early.
meta: The chain served and as_of. On a non-empty page meta also carries page_self_payments, page_self_payment_usd, page_gross_usd and page_organic_usd. All four are THIS PAGE only, as the names say: they are not site-wide figures and summing them across pages is not a total. self_payments_excluded is set when the page was filtered.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Rows to return. Clamped to 100; values outside the range are clamped, not rejected. | |
| before | No | Opaque cursor from a previous response's `next_before`. It encodes the whole sort key, tiebreaker included, so a page boundary inside a group of rows sharing a timestamp does not skip the rest. Do not parse it or build one by hand. | |
| min_probability | No | Keep only rows at or above this x402 confidence. `1.0` is proven by a named facilitator having relayed it; `0.05` is a bare transfer to a catalogued address. Read `evidence` on the row rather than thresholding this number blind — the ladder has five rungs and the gap that matters is `verified: true` against `verified: null`, not a decimal. | |
| exclude_self_payments | No | Set to `true` to drop rows where payer = payee. Off by default: a feed is a record of what happened and a wallet paying itself did happen, so the rows are ANNOTATED (`is_self_payment`) rather than hidden. Applied after the page is read, so a filtered page can be short of `limit` while more rows remain — keep following `next_before`. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/openWorld/non-destructive, and the description adds substantial context beyond them: the API-key auth requirement, the wrapped endpoint GET /v0/transactions, the three-valued `verified` semantics (true / false / null-not-disproven), and the warning that meta aggregates are page-scoped and not summable.
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 one-sentence purpose, then a structured Returns block with bolded field names; nearly every sentence carries information. Minor waste where return-value prose re-explains filter behavior already covered in the 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 no output schema, the description must carry the return contract, and it does: field-by-field semantics for transactions, next_before, and meta, including the non-obvious caveats that matter for correct aggregation. An agent can paginate and interpret results without guessing.
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 parameter descriptions are already detailed (cursor opacity, clamping, five-rung confidence ladder), so the bar is high. The description adds only marginally — clarifying that `next_before` is minted from rows read so `exclude_self_payments` cannot end the walk early — which largely restates the schema's own exclude_self_payments note.
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 first sentence gives a specific verb+resource ('every indexed settlement, newest first') and scoping ('global' feed) that implicitly separates it from entity-scoped siblings such as list_entity_settlements. It never names an alternative explicitly, so differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied through the filter semantics and pagination instructions ('keep following next_before'), but there is no explicit statement of when to choose this feed over list_entity_settlements or run_sql, and no exclusions or prerequisites beyond the API-key note.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
All settling wallets, filterable by the role they were seen in.
Wraps GET /v0/wallets. Access: requires an API key (Authorization: Bearer rh_live_… or x-api-key).
Returns:
wallets: Wallet rows with role and last seen.
next_before: Cursor for the next page, or null.
meta: The chain served and as_of. On an EMPTY list it also carries dataset_last_written_at, dataset_row_count and any warnings (e.g. endpoints_catalog_stale) — so a zero can be read as a quiet market or a stalled ingest rather than guessed at.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | Restrict to one observed role. | |
| limit | No | Rows to return. Clamped to 100; values outside the range are clamped, not rejected. | |
| before | No | Opaque cursor from a previous response's `next_before`. It encodes the whole sort key, tiebreaker included, so a page boundary inside a group of rows sharing a timestamp does not skip the rest. Do not parse it or build one by hand. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes well beyond the readOnly/openWorld annotations by disclosing the auth scheme (Bearer rh_live_… or x-api-key), the underlying endpoint, cursor-based pagination with a null terminator, and the non-obvious fact that an empty list returns dataset freshness fields and warnings. That empty-vs-stalled distinction is exactly the kind of context structured fields 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 one-line purpose, then endpoint, auth, and a bulleted return breakdown. Every line carries information an agent needs, and the empty-result caveat is placed where paging behavior is discussed rather than buried.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description fully documents the return shape (wallets, next_before, meta), the auth requirement, and the paging contract. Nothing an agent needs to call this correctly and interpret an empty page is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3; the description earns one more by linking the response's `next_before` to the paging loop, which makes the request/response cursor relationship clear. It does not re-explain the role enum values or the limit clamping, leaving that to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'All settling wallets, filterable by the role they were seen in', which unambiguously separates it from the transaction, agent, and merchant getters in the sibling set. It stops short of naming a sibling or contrasting with, say, list_transactions-scoped wallet data, so it is clear but not sibling-differentiating.
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 role filter implies usage ('filterable by the role they were seen in'), and the pagination cursor implies iterative paging, but there is no explicit when-to-use or when-not-to-use statement and no named alternative for related lookups. Adequate implied guidance, no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A ranked shortlist of endpoints that do this job, under criteria you choose and the response echoes back. Every term is something the endpoint publishes about itself — its listed price against the going rate, and its own reported demand. Roundhouse does not endorse any provider, and there is no cross-capability ranking. Only confident matches are ever recommended.
Wraps GET /v0/unified/{slug}/recommend. Access: no API key required.
Returns:
capability: The registry entry for the job being shortlisted.
criteria: Your criteria, echoed — a recommendation whose basis is invisible is an opinion.
price: The capability's going rate, so each candidate's index has context.
candidates: Ranked endpoints, each with reasons for where it placed.
considered: How many confident offers were ranked before filters.
excluded: How many were dropped, by which filter.
truncated: True when the candidate read hit its cap.
note: What the ranking is and is not — Roundhouse endorses no provider.
| Name | Required | Description | Default |
|---|---|---|---|
| live | No | Only endpoints answering when last probed. | |
| slug | Yes | Capability slug, from `/v0/unified`. | |
| limit | No | Rows to return. Clamped to 25; values outside the range are clamped, not rejected. | |
| model | No | Require the endpoint to name this model family (inference capabilities only). | |
| prefer | No | What to weight: cheapest, most-used, or an even split. | balanced |
| max_price | No | Hard ceiling in USDC per call. Endpoints with no published price are excluded when set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and destructiveHint=false, so the description's job is to add context beyond that, which it does: no API key required, no provider endorsement, only confident matches recommended, plus truncation and exclusion counts. Missing only rate-limit or freshness details.
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 sentence leads, followed by endpoint and access details, then a bulleted return contract. Most of it earns its place, though the first sentence is wordy and the returns list is long without an output schema to offload that detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description compensates by documenting every returned field (candidates, considered, excluded, truncated, note). Combined with access notes and the no-endorsement caveat, an agent has enough to call and interpret this open-world recommendation 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?
Schema coverage is 100%, so all six parameters, including the prefer enum and the max_price ceiling behavior, are already documented in the schema. The description adds no parameter-specific meaning beyond implying that criteria are echoed back in the response.
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 opening sentence states a specific verb and resource: a ranked shortlist of endpoints for a capability. It is clearly distinct from siblings such as get_capability (one entry) and list_capabilities (a catalog), though it never names an alternative directly.
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 the ranking philosophy ('under criteria you choose', 'Only confident matches') but gives no explicit when-to-use or when-not-to-use guidance. It never says when to reach for this versus run_sql or get_capability directly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
One SELECT (or WITH) over the public data-layer tables. Enforced in the database, not the worker: a read-only transaction as a role that can see only those tables, a statement timeout set by the TIER, and a hard 300-row cap. No semicolons, no comments, no multi-statement.
Priced by the time it takes: one Query Unit per started 5 seconds, floor of 1 — so a query that answers quickly costs 1, which is what every query cost before this was metered. tier buys the ceiling (standard 15s, extended 60s and a paid plan); the tier maximum is HELD when the call starts and the unused part released the moment the duration is known, so usage.units_charged on the response is the settled figure. Call get_account for the tier table, or send explain_only to be quoted without running or paying for anything.
Wraps POST /v0/sql. Access: an organization API key on any plan, metered against that organization’s Query Unit balance at 1 unit per started 5 seconds of query time. A paid plan buys the longer 60-second tier, not the route. A trial key belongs to no organization and is refused with the x402 price of one query instead of being served.
Returns:
rows: Result rows.
row_count: Number of rows returned.
duration_ms: Server-side execution time. This is what the call is priced on.
authenticated: Whether a key was accepted.
tier: The CREDENTIAL: anonymous, trial, or an organization tier.
sql_tier: The QUERY: which ceiling this run was given and priced at. A separate field from tier, which has always meant the credential.
quote: What the query was quoted at before it ran: the tier's ceiling and price bounds, plus the planner's own planner_cost and plan_rows. The planner figures are ADVISORY — arbitrary units, uncalibrated against this schema — and never charge anything; settlement is from measured duration, which needs no calibration to be right.
usage: What this call cost and what is left. units_charged is SETTLED, not the hold: the tier maximum is taken up front and the unused part released once the duration is known.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | A single read-only SELECT (or WITH) statement over the public dataset. No semicolons, no comments, no platform internals. Row cap 300. | |
| limit | No | Rows to return. Clamped to 300. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint/destructiveHint/openWorld, but the description adds substantial value beyond them: DB-enforced read-only role, tier-based statement timeout, hard 300-row cap, per-5-second Query Unit pricing, and the exact auth failure mode ('a trial key belongs to no organization and is refused'). The only blemish is describing a `tier` selector and `explain_only` flag that the schema does not expose.
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 core constraint is correctly front-loaded in the first sentence, but the body is long and repeats itself — the per-5-second pricing and the hold-then-settle mechanic are explained in the pricing paragraph, again in the Access paragraph, and a third time under `usage.units_charged`. Roughly a third of the text could be cut without losing information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, documenting the return fields (rows, row_count, duration_ms, quote, usage) is genuinely necessary and done well, including the warning that planner_cost is advisory and uncalibrated. Auth requirements, row cap and timeouts are all covered; only the phantom `tier`/`explain_only` references keep it from being fully trustworthy.
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 two real parameters, so the baseline would be 3, but the description actively introduces semantics for parameters that do not exist ('`tier` buys the ceiling (standard 15s, extended 60s)' and 'send `explain_only`'). An agent reading this would construct calls that fail validation, which is worse than adding nothing.
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 ('One SELECT (or WITH) over the public data-layer tables') plus the enforcement model, which immediately separates it from the list_*/get_* siblings that return canned collections. An agent can tell this is the ad-hoc query escape hatch 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?
It gives real routing advice — 'Call get_account for the tier table' — and frames the cost model so an agent can judge whether a query is worth running. But it also directs the agent to 'send `explain_only`' and says '`tier` buys the ceiling', and neither is a parameter in the schema (additionalProperties: false), so the guidance points at options that will be rejected. That undercuts otherwise strong when-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
get_accountget_agentget_capabilityget_graphget_leaderboardget_merchantlist_agent_feedbacklist_agentslist_capabilitieslist_entity_settlementslist_facilitatorslist_flowslist_serviceslist_transactionslist_walletsrecommend_capability_offersrun_sqlPay-per-query x402 business intelligence on Base, settled in USDC via the native 402 payment flow.
Base on-chain data for agents: balances, prices, transfers, Basenames, contracts. x402 pay-per-call.
Read-only Proof of Agent explorer: epochs, rewards, holders, swaps and agent census. No auth.
Pay-per-call x402 services for agents: risk scoring, DeFi, wallet and market data.
Add one secure layer between your agents and this server.
