firecrawl / firecrawl/firecrawl-mcp-server
MCP tool descriptions teach models the wrong calling convention, causing systematic tool-call failures
- Dominant language
- JavaScript
- Stars
- 7.5k
- Forks
- 884
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 14
Description
Some models using Firecrawl MCP call the tools using incorrect format e.g.
```
'arguments': '{"name":"firecrawl_search","arguments":{"query":"My search query", "limit":5}}'
```
which causes an error:
```
"MCP error -32602: Tool 'firecrawl_search' parameter validation failed: query: Invalid input: expected string, received undefined.
```
A correct way to call the tool is to use flat arguments, matching `input_schema` directly.
```
'arguments': '{"query":"My search query", "limit":5}'
```
Upon inspection, it seems that models learn this behaviour from Firecrawl MCP itself - its tool descriptions (served via MCP's `tools/list`) include "Usage Example" code blocks that wrap arguments in `{"name": "", "arguments": {...}}` envelope (the format that fails). This confuses weaker models (like `gpt-5-nano`) that read examples from `description` and try to imitate them.
A workaround is to explain to model how to invoke Firecrawl tools correctly, by adding something like this to the prompt:
```
IMPORTANT: When calling any Firecrawl MCP tool, pass arguments as a flat JSON object
matching the tool's schema. Do NOT wrap them in a {"name": ..., "arguments": ...}
envelope — that is a documentation display format, not the MCP calling convention.
```
But I believe the proper solution is to fix those usage examples.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start at the MCP tools/list response and inspect how each tool's description and Usage Example are assembled. Replace examples that show the {"name": ..., "arguments": {...}} envelope with flat arguments matching input_schema, then verify the advertised calls no longer teach the failing format.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- api
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100