Firecrawl MCP Server

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

Annotations already establish a safe read-only, non-destructive, closed-world operation, and the description adds substantial context on top: the two-phase upload behavior, what each call returns, PII redaction semantics, the zeroDataRetention account requirement, and the optional scrapeId feedback hook. None of this is derivable from the annotations.

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

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

Front-loaded with purpose and formats, then mechanics, then caveats, with no filler sentences. The one return-value sentence is arguably redundant given the output schema, but it is short and useful for disambiguating the two-phase flow.

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

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

For a 19-parameter tool with nested objects, the description nails the invocation flow and a few key flags but omits guidance on the options that govern the requested output modes (json/query schemas, tag filtering, formats/parsers). The presence of an output schema excuses return-value detail, but the parameter gaps keep this at minimum-viable.

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

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

With only 26% schema description coverage across 19 parameters, the description must compensate more than it does. It meaningfully explains redactPII, zeroDataRetention, pdfOptions.maxPages, filePath and uploadRef, but leaves format-driving options (jsonOptions, queryOptions, includeTags/excludeTags, formats, parsers) undocumentable in either place.

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

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

States a specific verb and resource ('Parse one supported document') and enumerates the output formats and the supported input file types. It also distinguishes itself from the sibling firecrawl_scrape by explicitly routing remote web URLs there.

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

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

Gives explicit operating conditions: local MCP reads filePath from the server filesystem, hosted MCP requires a two-call upload handshake with the warning not to send both fields together, and remote URLs belong in firecrawl_scrape. It also states the auth precondition for zeroDataRetention and tells anonymous users to omit it.

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

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

Annotations declare readOnlyHint=false, destructiveHint=false, openWorldHint=true, but the description adds genuinely non-obvious behavior: cached/recently-indexed content and the maxAge=0 escape hatch, the caveat that a successful response does not confirm freshness, that browser actions can mutate the live page, scrapeId feedback, and keyless-session limitations. It stops short of describing pagination or partial-failure behavior for URL mode, so it is not a 5.

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

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

The first paragraph is well front-loaded and earns its place, but the second and third paragraphs are dense run-on sentences with heavy qualifiers ('On an authenticated session with Alexandria access, firecrawl_search with sources unset and firecrawl_find_tools can discover providers...'). The content is relevant but the structure makes it hard to scan.

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

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

Given a 27-parameter tool with nested objects and an output schema, the description covers the important mode distinctions, freshness semantics, auth requirements, and the alexandria-exclusive mode. Return values are covered by the output schema. The main gap is the undocumented parameter surface, which is partly excusable given the volume.

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

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

Schema description coverage is only 19% across 27 parameters, so the description carries a heavy burden. It glosses the format options and explains maxAge and the alexandria/url mutual exclusion, but leaves the majority of parameters (proxy, location, parsers, profile, screenshotOptions, jsonOptions, redactPII, lockdown, and more) undocumented in both places.

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

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

Opens with a specific verb+resource ('Scrape one URL') and enumerates the concrete output formats the caller can request. It explicitly separates itself from firecrawl_search, firecrawl_map, and firecrawl_crawl by naming the condition that selects each.

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

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

States the selection condition ('when the request identifies a page and needs its content or defined fields') and names the alternatives with their own triggers. The Alexandria paragraph adds a clear mutually-exclusive usage path with its own precondition (authenticated session with Alexandria access).

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

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

Annotations cover read-only/open-world safety, but the description goes further: keyless vs authenticated behavior diverges (no Alexandria matches), default sources differ by session, scrapeOptions fetches ignore maxAge, and an optional search-feedback id is returned. These auth- and session-dependent traits are not derivable from annotations or schema.

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

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

Dense but mostly front-loaded and every paragraph carries routing or auth information. Some Alexandria/tool-discovery detail is repeated across sentences (toolDetail vs firecrawl_find_tools appears twice), costing a little tightness.

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

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

For a 14-parameter, nested-schema, open-world search tool with an output schema, the description covers session-dependent defaults, provider-vs-scrape tradeoffs, category semantics, and return grouping without redundantly explaining the document-return schema.

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

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

Schema coverage is only 64%, and the description meaningfully compensates for several under-documented params (sources defaults, domainTools defaults and web-only behavior, toolDetail compact/full semantics, categories including developer/research). It does defer operators and scrapeOptions to the parameter docs, which is reasonable since those are well-described in the schema.

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

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

States a specific verb (search) and resource (web, news, image sources) plus the return shape (ranked results with highlights). It also distinguishes itself from firecrawl_scrape by naming when to use that sibling instead of this one.

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

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

Explicit routing rules: use firecrawl_scrape when the excerpt is insufficient, prefer an Alexandria provider when the task spans several entities or needs exact figures, use web results when they already answer. Also explains sources/domainTools interactions and category selection.

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