Skip to main content
Glama

Firecrawl by Nova (CIVAI)

firecrawl_agent

Run web research that returns structured data when the URLs are not known or the answer spans several sites. Describe the fields you need in prompt, optionally pass a JSON schema and seed urls, and the research agent searches, navigates, reads pages, and returns JSON assembled across sources. Use it to research an entity plus its fields (founders, pricing, contact details), to build lists and datasets (companies, people, products, jobs, papers), and for pages that need navigation or interaction to reach the data. Optional effort sets the reasoning budget, maxCredits caps spend, and strictConstrainToURLs keeps the agent to the supplied urls.

This call returns only a job ID, not the research result. Read the job with firecrawl_agent_status until it reaches completed or failed; a typical research run takes one to three minutes. For one known URL use firecrawl_scrape (with formats: ["markdown"], then extract the requested fields yourself); for a plain lookup that a results page answers, use firecrawl_search.

The job also returns a threadId. To continue that thread, pass it with a follow-up prompt; omitted mode, urls, schema and exchange settings carry over from the previous turn.

The agent only calls Alexandria providers whose terms the team has accepted. exchange.skippedProviders lists gated providers. With exchange.onTermsRequired "ask", a terms pendingApproval and exchange.requiresAction carry the approvalId and provider requirements. Read terms/show through firecrawl_scrape. An organization admin must accept terms in the Firecrawl dashboard at the provider URL or https://www.firecrawl.dev/app/settings?tab=data-sources. Ignore any terms/accept call in the API response. Only after the admin confirms acceptance, resume with the same threadId and exchange.approve: {approvalId}; this does not accept terms. To decline, use exchange.decline: {approvalId}. Never infer acceptance from a data request.

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": {
      "prompt": "<prompt>"
    },
    "name": "firecrawl_agent"
  }
}

Input Schema

NameRequiredDescriptionDefault
modeNo"extract" (default) returns the complete structured result every turn. "chat" lets a follow-up that asks no new data get a short reply in message instead of a re-run; required for exchange.requireApproval. Omitted on a follow-up keeps the previous turn's mode.
urlsNo
effortNoReasoning budget for the agent task.
promptYes
schemaNo
exchangeNoAlexandria provider settings for this turn, forwarded as the request's exchange object.
threadIdNoContinue this thread: the threadId from an earlier firecrawl_agent or firecrawl_agent_status result. Omit to start a new thread.
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.
maxCreditsNoSpending limit in credits for this run. Defaults to 2500 on the API.
conversationIdNoconversationId from any earlier Firecrawl tool result in this conversation; after parallel calls, any one of theirs. Omit only on the first call of a conversation; the result returns one to pass on every later call.
zeroDataRetentionNoRun with zero data retention. Requires an eligible authenticated account with Zero Data Retention enabled for both scrape and search. Cannot be combined with threadId.
strictConstrainToURLsNoIf true, agent will only visit URLs provided in the urls array.

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. Changed1 schema field changed
    • addedInput schema / properties / zeroDataRetention
      Added value: +{
      +  "description": "Run with zero data retention. Requires an eligible authenticated account with Zero Data Retention enabled for both scrape and search. Cannot be combined with threadId.",
      +  "type": "boolean"
      +}
  3. Changed1 schema field changed
    • removedInput schema / properties / urls / items / format
      Removed value: -"uri"
  4. Changed1 schema field changed
    • changedInput schema / properties / schema / additionalProperties
      Previous value: -{}New value: +true
  5. First observed

TDQS

A4.8/5.0
Behavior5/5

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

With no annotations, the description carries the full burden and does so: it discloses that the call returns only a job ID, that results must be read via firecrawl_agent_status until completed/failed, and that a run typically takes one to three minutes. It also explains thread continuation via threadId, credit capping through maxCredits, and the gated-provider terms flow (skippedProviders, pendingApproval, requiresAction, admin-only acceptance in the dashboard, and that approve does not itself accept terms).

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?

Purpose, alternatives, and async polling are front-loaded, and nearly every sentence carries operational weight. The terms/approval paragraph is long and dense, including a dashboard URL and an 'ignore any terms/accept call' caveat, which costs some readability even though the information is necessary.

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?

For a 12-parameter asynchronous research tool with no output schema and a nested exchange object, the description covers the return shape (job ID plus threadId), the polling loop, thread resumption semantics, and the multi-step approval workflow. An agent has everything needed to invoke it and follow up 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 coverage is 75%, and the description adds genuine meaning beyond it: prompt should describe the fields you need, schema is optional JSON for structure, urls seed the run, effort sets reasoning budget, maxCredits caps spend, and strictConstrainToURLs confines the agent to supplied URLs. It also explains the threadId carry-over rule for omitted parameters. It says nothing about mode, objective, conversationId, or zeroDataRetention in prose, leaving those to the schema.

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?

The opening sentence gives a specific verb and resource (run web research returning structured data) plus the exact conditions that define it: URLs unknown or the answer spans several sites. It also distinguishes itself from firecrawl_scrape and firecrawl_search, so an agent can pick the right tool 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?

It states explicit positive cases (research an entity plus its fields, build lists/datasets, pages needing navigation) and explicit alternatives with the condition that selects them: firecrawl_scrape for one known URL with markdown format, firecrawl_search for a results-page lookup, and firecrawl_agent_status to poll. When-to-use and when-not-to-use are both covered.

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