Spicrawl

Usage breakdown

spicrawl_usage

Read-onlyIdempotent

Billing-grade usage for your org over a date window, from the daily rollup (usage_daily), grouped by day, project, engine, feature or key. group_by=key returns per API key (key_id, name, prefix, project_id) counters per metric per day, from usage_key_daily; keyless (dashboard) usage is not in it, and a project-scoped key sees only its own project's keys. Use it to answer 'how many requests/credits did I use, and where'. The window defaults to the last 30 days including today; to is EXCLUSIVE (a single day 2026-08-01 is from=2026-08-01, to=2026-08-02) and the window may not exceed 400 days. The response carries stale_seconds (age of the newest rollup row; null when the window is empty). Requires the key to have the read scope.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "spicrawl_usage"
  }
}

Input Schema

Name	Required	Description
`to`	No	EXCLUSIVE end date, YYYY-MM-DD (UTC). Default: tomorrow, so today is included.
`from`	No	Inclusive start date, YYYY-MM-DD (UTC). Default: 29 days before today.
`metrics`	No	Metrics to return. Omit for all of them.
`group_by`	No	How to group the rows. Default 'day'.
`project_id`	No	Restrict to one project id (must be a valid Spicrawl identifier).

Output Schema

Name	Required	Description
`keys`	No	group_by=key only: one entry per API key, with its counters per UTC day.
`groups`	No	The buckets, sorted by key. Empty (or missing for group_by=key) does not mean no usage: read totals.
`period`	No	The window, as a half-open range of UTC days.
`totals`	No	Billed quantities for the whole window. Authoritative; use these, not the sum of groups.
`group_by`	No	The dimension used: day, project, engine, feature or key.
`warnings`	No	Caveats the numbers would otherwise hide.
`usage_as_of`	No	When the newest rollup row in the window was written; null when the window is empty.
`unattributed`	No	The part of each total the groups do not explain.
`stale_seconds`	No	Age of usage_as_of in seconds; null when the window is empty. A large value means the rollup is behind.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 13, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": true,
+  "properties": {
+    "group_by": {
+      "description": "The dimension used: day, project, engine, feature or key.",
+      "type": "string"
+    },
+    "groups": {
+      "anyOf": [
+        {
+          "items": {
+            "additionalProperties": true,
+            "properties": {
+              "key": {
+                "description": "The bucket: a YYYY-MM-DD day, a project id, an engine tier (fetch, js or browser) or a feature (extract, ai_extract, proxy_datacenter, proxy_residential, batch).",
+                "type": "string"
+              },
+              "label": {
+                "description": "Human label for an engine tier.",
+                "type": "string"
+              },
+              "metrics": {
+                "anyOf": [
+                  {
+                    "additionalProperties": {
+                      "type": "number"
+                    },
+                    "type": "object"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Metric name -> quantity. credits are micro-credits (1 credit = 1000000), engine_ms milliseconds, bytes_* bytes, the rest counts."
+              }
+            },
+            "required": [
+              "key"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The buckets, sorted by key. Empty (or missing for group_by=key) does not mean no usage: read totals."
+    },
+    "keys": {
+      "anyOf": [
+        {
+          "items": {
+            "additionalProperties": true,
+            "properties": {
+              "days": {
+                "anyOf": [
+                  {
+                    "items": {
+                      "additionalProperties": true,
+                      "properties": {
+                        "day": {
+                          "type": "string"
+                        },
+                        "metrics": {
+                          "$ref": "#/properties/groups/anyOf/0/items/properties/metrics"
+                        }
+                      },
+                      "required": [
+                        "day"
+                      ],
+                      "type": "object"
+                    },
+                    "type": "array"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ]
+              },
+              "key_id": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "prefix": {
+                "description": "Display prefix of the API key, never the secret.",
+                "type": "string"
+              },
+              "project_id": {
+                "type": "string"
+              },
+              "revoked": {
+                "type": "boolean"
+              },
+              "totals": {
+                "$ref": "#/properties/groups/anyOf/0/items/properties/metrics",
+                "description": "Metric name -> quantity. credits are micro-credits (1 credit = 1000000), engine_ms milliseconds, bytes_* bytes, the rest counts."
+              }
+            },
+            "required": [
+              "key_id"
+            ],
+            "type": "object"
+          },
+          "type": "array"
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "group_by=key only: one entry per API key, with its counters per UTC day."
+    },
+    "period": {
+      "additionalProperties": true,
+      "description": "The window, as a half-open range of UTC days.",
+      "properties": {
+        "bounds": {
+          "description": "Always '[start, end)'.",
+          "type": "string"
+        },
+        "days": {
+          "type": "number"
+        },
+        "end": {
+          "description": "End UTC day, EXCLUSIVE (YYYY-MM-DD).",
+          "type": "string"
+        },
+        "start": {
+          "description": "First UTC day, inclusive (YYYY-MM-DD).",
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "stale_seconds": {
+      "description": "Age of usage_as_of in seconds; null when the window is empty. A large value means the rollup is behind.",
+      "type": [
+        "number",
+        "null"
+      ]
+    },
+    "totals": {
+      "$ref": "#/properties/groups/anyOf/0/items/properties/metrics",
+      "description": "Billed quantities for the whole window. Authoritative; use these, not the sum of groups."
+    },
+    "unattributed": {
+      "$ref": "#/properties/groups/anyOf/0/items/properties/metrics",
+      "description": "The part of each total the groups do not explain."
+    },
+    "usage_as_of": {
+      "description": "When the newest rollup row in the window was written; null when the window is empty.",
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "warnings": {
+      "description": "Caveats the numbers would otherwise hide.",
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "type": "object"
+}

First observedOct 1, 2026

TDQS

A4.3/5.0

Behavior5/5

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

Annotations cover only the safety profile (readOnly/idempotent/non-destructive), and the description adds substantial context beyond them: the default 30-day window, the EXCLUSIVE end date with a worked example, a hard 400-day window cap, the stale_seconds freshness field, the requirement for the `read` scope, and the blind spot for keyless usage. That is a rich, non-obvious behavioral disclosure.

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?

It is a single dense paragraph rather than a bulleted spec, which hurts scannability slightly, but the most important facts (what it returns, what it excludes, then window/date semantics, then auth) are front-loaded and each sentence carries non-redundant information. No filler.

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?

An output schema exists, so the description rightly does not enumerate return fields; it still flags the one response property worth knowing (stale_seconds). Combined with window bounds, exclusivity, grouping caveats and the required scope, an agent has everything needed to call this 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?

Schema description coverage is already 100%, so the baseline is 3, but the description goes further by explaining semantics the schema only gestures at: `to` is exclusive with a single-day example, the default window is last 30 days including today, and group_by=key changes both the source table and the returned counter shape. Minor gaps remain around how metrics interact with grouping, but the added meaning is real.

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

Purpose4/5

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

The description states a specific verb+resource: billing-grade org usage over a date window, drawn from the usage_daily rollup and groupable by day/project/engine/feature/key. It even names the alternate source table (usage_key_daily) for key grouping. It never names its obvious siblings (spicrawl_usage_summary, spicrawl_usage_reconciliation), so the agent gets no explicit differentiation within the usage family.

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

Usage Guidelines4/5

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

It gives a concrete usage condition: "Use it to answer 'how many requests/credits did I use, and where'", and supplies negative scoping for group_by=key (keyless dashboard usage is absent; a project-scoped key only sees its own project). It stops short of stating when to prefer this over spicrawl_usage_summary or spicrawl_usage_reconciliation.

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

All Spicrawl 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?