firecrawl / firecrawl/firecrawl-mcp-server

MCP tool descriptions teach models the wrong calling convention, causing systematic tool-call failures

Open
#279 0 comments 2 reactions 0 assignees View on GitHub
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.