whale-insights

whale_movements_summary

Read-onlyIdempotent

Whale movements summary — aggregated stats rollup (no auth, MCP-compatible) — Returns an aggregated statistics rollup of whale on-chain movements over a period, so AI agents don't have to page through raw /api/public/whale-movements rows to compute totals themselves. Breaks down movement counts and REAL USD totals (from the same usd_value column as /api/public/whale-movements) by chain and by flow direction (inflow/outflow/transfer). USD totals only ever include rows with a resolvable price — unresolvedUsdCount reports how many movements in the window had no resolvable USD value, so totals are never silently inflated or fabricated. period filter: 7d | 30d | 90d (default 7d — a shorter default than the raw archive's 90d, since a rollup is most useful over a recent window). Response: { sinceDays, movementCount, movementsWithResolvedUsd, unresolvedUsdCount, totalUsd, byDirection, usdByDirection, topChainsByUsd[], firstSeenAt, lastSeenAt, dataSource, updatedAt }. No authentication required. 60 requests/min rate

Input Schema

TableJSON Schema

Name	Required	Description	Default
`period`	No	Time window: 7d \| 30d \| 90d (default 7d).	7d

Output Schema

TableJSON Schema

Name	Required	Description
`totalUsd`	No	Sum of usd_value across all resolved movements in the window (whole dollars).
`sinceDays`	No	Number of days covered by this summary.
`updatedAt`	No
`dataSource`	No
`lastSeenAt`	No
`attribution`	No
`byDirection`	No	Movement counts by flow direction.
`firstSeenAt`	No
`movementCount`	No	Total whale movements recorded in the window.
`topChainsByUsd`	No	Up to 10 chains ranked by total resolved USD volume in the window.
`usdByDirection`	No	Real USD totals by flow direction (resolved rows only).
`unresolvedUsdCount`	No	Movements with no resolvable USD value — excluded from every USD sum below.
`movementsWithResolvedUsd`	No	Subset of movementCount that had a resolvable USD value.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedSep 3, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "attribution": {
+      "$ref": "#/components/schemas/Attribution"
+    },
+    "byDirection": {
+      "description": "Movement counts by flow direction.",
+      "properties": {
+        "inflow": {
+          "type": "number"
+        },
+        "outflow": {
+          "type": "number"
+        },
+        "transfer": {
+          "type": "number"
+        },
+        "unknown": {
+          "type": "number"
+        }
+      },
+      "type": "object"
+    },
+    "dataSource": {
+      "type": "string"
+    },
+    "firstSeenAt": {
+      "format": "date-time",
+      "nullable": true,
+      "type": "string"
+    },
+    "lastSeenAt": {
+      "format": "date-time",
+      "nullable": true,
+      "type": "string"
+    },
+    "movementCount": {
+      "description": "Total whale movements recorded in the window.",
+      "type": "number"
+    },
+    "movementsWithResolvedUsd": {
+      "description": "Subset of movementCount that had a resolvable USD value.",
+      "type": "number"
+    },
+    "sinceDays": {
+      "description": "Number of days covered by this summary.",
+      "type": "number"
+    },
+    "topChainsByUsd": {
+      "description": "Up to 10 chains ranked by total resolved USD volume in the window.",
+      "items": {
+        "properties": {
+          "chain": {
+            "type": "string"
+          },
+          "inflow": {
+            "type": "number"
+          },
+          "movementCount": {
+            "type": "number"
+          },
+          "outflow": {
+            "type": "number"
+          },
+          "totalUsd": {
+            "type": "number"
+          },
+          "transfer": {
+            "type": "number"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "totalUsd": {
+      "description": "Sum of usd_value across all resolved movements in the window (whole dollars).",
+      "type": "number"
+    },
+    "unresolvedUsdCount": {
+      "description": "Movements with no resolvable USD value — excluded from every USD sum below.",
+      "type": "number"
+    },
+    "updatedAt": {
+      "format": "date-time",
+      "type": "string"
+    },
+    "usdByDirection": {
+      "description": "Real USD totals by flow direction (resolved rows only).",
+      "properties": {
+        "inflow": {
+          "type": "number"
+        },
+        "outflow": {
+          "type": "number"
+        },
+        "transfer": {
+          "type": "number"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

AddedJul 10, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Annotations already declare readOnly, idempotent, and non-destructive, and the description adds valuable behavioral context: USD totals only include rows with resolvable prices, unresolvedUsdCount prevents silent inflation/fabrication, and no auth or rate limits are stated. This goes well beyond the structured annotations.

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?

The description is front-loaded with purpose and rich in useful detail. There is slight redundancy between 'aggregated stats rollup' in the opening and 'aggregated statistics rollup' in the next sentence, but every other sentence earns its place with concrete behavioral and operational information.

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

Completeness5/5

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

Given one optional parameter, an output schema, and annotations, the description is complete: it covers the response shape, period handling, USD resolution caveats, auth, rate limit, and data source. An agent has everything needed to invoke and interpret this tool correctly.

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?

Input schema covers the single period parameter with enum values and default, so the baseline is 3. The description adds semantic value by explaining why the default is 7d and why that differs from the raw archive, which helps an agent reason about parameter choice.

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?

Clearly states it returns an aggregated statistics rollup of whale on-chain movements over a period, with specific breakdowns by chain and flow direction. It explicitly differentiates itself from the raw whale_movements tool by explaining that agents don't need to page through raw rows to compute totals.

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?

Provides explicit guidance on when to use this tool instead of the raw whale-movements endpoint: when an agent wants totals without manually aggregating rows. It also explains the default period choice (7d) relative to the raw archive's 90d, giving a clear context for selecting the right tool and parameter.

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

All whale-insights 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.

Resources

Need Help?