Skip to main content
Glama

Firecrawl by Nova (CIVAI)

firecrawl_credit_usage

Get the authenticated Firecrawl team's current credit balance or its credit usage over the last 90 days. Use the current view to answer how many credits remain or to check billing-period boundaries. Use the historical view to answer what credits were spent on and when.

The current view returns remainingCredits, planCredits, billingPeriodStart, and billingPeriodEnd. Extra purchased or granted credits can make remainingCredits greater than planCredits. Billing-period dates may be null when the upstream billing provider has no period metadata.

The historical view returns periods sorted by start date with startDate, endDate, and creditsUsed, one per calendar month, or one per UTC day with bin: "day". Set byEndpoint to split each period by the endpoint that used the credits (endpoint: scrape, search, crawl, map, agent, ...), or byApiKey to split it by API key (apiKey). The endpoint split also counts search usage, which the unsplit and per-key figures leave out, so its rows can add up to more. The newest period's endDate can be null. A notice means the requested split or daily periods are not available yet and the periods are monthly figures.

This tool cannot attribute credits to individual jobs, URLs, or MCP clients. Each tool's own result reports what that call used (creditsUsed, or metadata.creditsUsed on scrapes), and the Usage and Logs pages of the Firecrawl dashboard list usage per job.

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": "firecrawl_credit_usage"
  }
}

Input Schema

NameRequiredDescriptionDefault
binNoLength of each historical period: calendar month (default) or UTC day. When view is omitted, it selects the historical view; it cannot be combined with view "current".
viewNoSelect current balance or historical usage. Defaults to current.
byApiKeyNoBreak historical usage down by API key. When view is omitted, true selects the historical view; it cannot be combined with view "current".
objectiveNoThe user's underlying goal in one sentence, not a restatement of this call's arguments. Reuse it across related calls. Firecrawl uses it to learn what agents need and improve its results. No personal data, secrets or the user's exact words.
byEndpointNoBreak historical usage down by endpoint (scrape, search, crawl, map, agent, ...). When view is omitted, true selects the historical view; it cannot be combined with view "current" or byApiKey.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changed
    • addedInput schema / properties / objective
      Added value: +{
      +  "description": "The user's underlying goal in one sentence, not a restatement of this call's arguments. Reuse it across related calls. Firecrawl uses it to learn what agents need and improve its results. No personal data, secrets or the user's exact words.",
      +  "maxLength": 5000,
      +  "minLength": 1,
      +  "type": "string"
      +}
  2. First observed

TDQS

A4.3/5.0
Behavior5/5

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

With no annotations supplied, the description carries the full burden and does so well: it enumerates returned fields per view, warns that remainingCredits can exceed planCredits, that billing dates and the newest endDate may be null, and that endpoint-split rows can exceed unsplit totals because search usage is counted differently. The notice semantics for unavailable splits is exactly the kind of behavior an agent cannot infer elsewhere.

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 front-loaded with purpose and view selection before the return-value detail, and each paragraph has a distinct job. It is on the long side for a read-only query tool, with some field-level enumeration that could be trimmed, but almost every sentence carries information an agent needs.

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?

There is no output schema, so the description must document return values itself, and it does so for both views including edge cases and nullability. For a five-parameter, zero-required reporting tool, nothing an agent needs to call it correctly is missing.

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%, so the baseline is 3; the description adds real meaning on top by explaining what byEndpoint and byApiKey actually split and why the endpoint split is numerically inconsistent with the other figures. It adds nothing about the `objective` parameter, which the schema already covers.

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 opening sentence gives a specific verb and resource ('Get the authenticated Firecrawl team's current credit balance or its credit usage over the last 90 days') and splits the tool into two clearly named views. It does not, however, distinguish itself from the sibling firecrawl_usage_dashboard, which an agent could plausibly confuse with this billing-oriented tool.

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 explicit selection rules per view: current for remaining credits and billing-period boundaries, historical for what was spent and when. It also states a hard exclusion ('cannot attribute credits to individual jobs, URLs, or MCP clients') and redirects to per-call creditsUsed and the dashboard Usage/Logs pages. The one gap is that no sibling MCP tool is named as an alternative.

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

Try in Browser

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources