Bitquery: Crypto & Blockchain Data

Eth Find Calls

eth_find_calls

Read-only

FIND SMART-CONTRACT CALLS on one Ethereum (eth, ETH, mainnet, L1) contract by method — "who called method X on contract Y, when, did it succeed" in one filtered query. NOT event logs a contract emitted → use eth_find_events. NOT what one address signed or received → use eth_transactions. Returns up to limit calls (default 20, at most 10000), newest first; page back with the last row's Cursor - each page covers the days window ending there. Match by method name (e.g. "transfer"), full signature ("transfer(address,uint256)"), or raw 4-byte selector (e.g. "a9059cbb"); optionally restrict to one caller. Searches the last 7 days by default — set after_time to reach further back. Includes reverted calls when only_successful=0 (with error text). Then inspect a transaction's fund movements with eth_tx_transfers. SCAN COST scales with the window, not with the limit: on a very high-traffic contract set days=1 and page back with cursor - several times cheaper than a 7-day window for the same page. Widen days for quiet contracts or rare matches. Calls inside one transaction come back in no particular order - sort them by CallPath if you need execution order. Each row carries the call's decoded input Arguments (Name, Type, Value; integers are decimal strings in raw units, NOT divided by token decimals; addresses as 0x-hex) - at most 32 per row: ArgumentCount is the full number and ArgumentsTruncated=1 marks a cut list (every array element counts as one). A method the decoder does not recognise has no Arguments. Value is the ETH attached to the call. Each row: Tx, Time, Block, Caller, Method, Signature, Selector, CallPath, Value, Success, Reverted, Error, GasUsed, Cursor, Arguments, ArgumentCount, ArgumentsTruncated.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "contract": "<contract>"
    },
    "name": "eth_find_calls"
  }
}

Input Schema

Name	Required	Description	Default
`days`	No	Size of the default scan window in DAYS, ending at the cursor position, before_time, or now. Ignored when after_time is set. Use days=1 on a very high-traffic contract and page back with cursor.
`limit`	No	Max calls to return (newest first). At most 10000.
`caller`	No	Only calls made by this address, 0x-hex (case-insensitive). Empty = any caller.
`cursor`	No	Exact paging cursor: pass the Cursor value of the LAST row of the previous page to get the next page. Prefer this over before_time, which skips any rows sharing the last row's timestamp (busy contracts often have hundreds in one second). When set, before_time is ignored and the scan window (days) is measured back from the cursor position. Empty = first page.
`format`	No	Shape of the returned data. "rows" (the default) returns one item per row. "columnar" returns a single item, {"columns":[...],"rows":[[value,...],...]}, naming the columns once and listing each row's values in that order; it is more compact for large results and carries the same values.	rows
`method`	No	Method to match — name (e.g. "transfer") or full signature (e.g. "transfer(address,uint256)"), case-insensitive. Empty = any method.
`contract`	Yes	Contract address that was called, 0x-hex (case-insensitive).
`selector`	No	Raw 4-byte selector, hex with or without 0x (e.g. "a9059cbb") — alternative to `method` for unrecognized methods. Empty = ignore.
`after_time`	No	Only calls at/after this UTC time. Empty = the default 7-day window. Format: YYYY-MM-DD, YYYY-MM-DD HH:MM[:SS], ISO-8601 like 2026-09-20T00:00:00Z (fraction or +02:00 offset allowed) or 10-digit unix seconds.
`before_time`	No	Only calls strictly before this UTC time. COARSE filter only — it drops every row that shares the last row's timestamp, so do not page with it; page with cursor. Ignored when cursor is set. Empty = up to now. Format: YYYY-MM-DD, YYYY-MM-DD HH:MM[:SS], ISO-8601 like 2026-09-20T00:00:00Z (fraction or +02:00 offset allowed) or 10-digit unix seconds.
`only_successful`	No	1 (default) = only successful calls in successful transactions; 0 = also include failed/reverted calls.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 28, 2026

addedInput schema / properties / format

Added value: +{
+  "default": "rows",
+  "description": "Shape of the returned data. \"rows\" (the default) returns one item per row. \"columnar\" returns a single item, {\"columns\":[...],\"rows\":[[value,...],...]}, naming the columns once and listing each row's values in that order; it is more compact for large results and carries the same values.",
+  "type": "string"
+}

First observedOct 7, 2026

TDQS

A4.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so safety is covered; the description adds real behavior beyond that: newest-first ordering, cursor-based paging, reverted calls only when only_successful=0, per-row argument truncation caps, and scan cost scaling with window rather than limit. It stops short of describing result-size limits or rate/quota behavior, but for a read-only tool with annotations this is solid coverage.

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

Conciseness4/5

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

Front-loaded with purpose, then exclusions, then paging, then cost, then return shape — a sensible information hierarchy with no stray sentences. It is long, and a few clauses (e.g. restating default 20 / max 10000) repeat what the schema already says, but the density is mostly justified given 11 parameters and no output schema.

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

Completeness5/5

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

With no output schema, the description carries the return contract itself: an enumerated per-row field list plus semantics for Arguments, ArgumentCount, ArgumentsTruncated, Value, and CallPath ordering. Combined with full parameter coverage and default-window behavior, an agent has everything needed to call this correctly and interpret the result.

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

Parameters4/5

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

Schema coverage is 100%, setting the baseline at 3, but the description adds meaning the schema lacks: the three accepted method-match forms (name, full signature, 4-byte selector), the explicit selector-vs-method relationship, and the crucial unit convention that Argument integers are raw decimal strings not divided by token decimals. The cursor-vs-before_time tradeoff and CallPath ordering caveat are also clarified beyond the field docs.

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

Purpose5/5

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

Opens with a specific verb and resource plus scope: find smart-contract calls on one Ethereum contract by method, framed as the 'who called method X on contract Y, when, did it succeed' question. It also names the two nearest siblings it is not (eth_find_events for event logs, eth_transactions for address activity), so the agent can discriminate without opening a schema.

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

Usage Guidelines5/5

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

Explicit when-not routing to eth_find_events and eth_transactions, plus a follow-on pointer to eth_tx_transfers. It also gives concrete selection guidance between days windows and cursor paging based on contract traffic, and states the default 7-day window with how to reach further back via after_time.

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

All Bitquery: Crypto & Blockchain Data tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.