Skip to content

[BUG] MCPClient silently drops empty [] and {} tool arguments (and list items that clean to empty) before they reach the MCP server #8045

Closed as not planned

Description

@BlueX888

Description

MCPClient._clean_tool_arguments silently deletes tool arguments whose value is an explicit empty list [] or empty dict {}, and deletes list items whose dict body cleans to empty, so the MCP server never receives them. When the LLM emits {"query": "cats", "tags": []} for a tool whose schema declares tags, the server only receives {"query": "cats"}. If the schema marks such a field required, the server rejects a schema-valid call the agent believed it made; if the field is optional, the server default silently replaces the explicit []. The list branch additionally deletes positional items: [{"opt": None}, 1] arrives as [1].

Explicit falsy scalars from the same call ("", 0) are preserved, so dropping falsy containers is an internal inconsistency rather than a deliberate falsy-argument policy.

Root cause — lib/crewai/src/crewai/mcp/client.py, in _clean_tool_arguments:

  • client.py:594 — if nested_cleaned: treats a cleaned empty dict as falsy and drops the key, so {} vanishes;
  • client.py:605 — if cleaned_list: treats an empty list as falsy and drops the key, so [] vanishes;
  • client.py:601-602 — a dict list item whose body cleans to empty is not appended, deleting the element and shifting positions;
  • client.py:607-608 — the scalar else branch passes "" and 0 through untouched.

Steps to Reproduce

  1. Install crewAI from main (I tested commit 4ed2abc7bbf504a634d3b733f2a97e0fbe8d44ec, installed as 1.15.22) with the mcp SDK present.
  2. Unit level — call _clean_tool_arguments directly with the snippet below: the tags/filters keys vanish and mixed shifts to [1], while label: "" and count: 0 survive.
  3. Wire level — await client.call_tool("search", {"query": "cats", "tags": []}): the MCP session receives only {"query": "cats"}.
  4. End-to-end against a real FastMCP stdio server: with optional tags/filters the server echoes {"query": "cats", "tags": null, "filters": null} (the keys never arrived); with a schema that marks tags required, the same schema-valid call is rejected by the server with Field required.

No API keys or network access are needed.

Expected behavior

Only None values should be removed. An explicit empty []/{} argument should reach the MCP server exactly as emitted, and list positions should be preserved.

Basis:

  • The function's own docstring (lib/crewai/src/crewai/mcp/client.py:563-571) documents the contract as "Clean tool arguments by removing None values and fixing formats" — only None removal is documented.
  • The scalar branch in the same function (client.py:607-608, else: cleaned[key] = value) deliberately preserves explicit falsy scalars — reproduced: label="" and count=0 survive cleaning. Dropping falsy containers while keeping falsy scalars is inconsistent, not policy.
  • A tool's MCP inputSchema (JSON Schema) distinguishes [] from absent: required: ["query", "tags"] accepts {"query": "cats", "tags": []} but not a missing tags. Deleting the key corrupts a schema-valid call, which is why the real server rejects it with Field required (see Evidence).

Screenshots/Code snippets

repro_clean_args.py — unit + wire levels (the mock session only replaces the transport boundary; the code under test is the repo's real _clean_tool_arguments):

import asyncio
from types import SimpleNamespace
from crewai.mcp.client import MCPClient

class FakeTransport:
    connected = True
    def __init__(self):
        self.transport_type = SimpleNamespace(value="fake")

class MockSession:
    def __init__(self):
        self.sent = []
    async def call_tool(self, name, arguments):
        self.sent.append((name, dict(arguments)))
        class _Text: text = "mock-result"
        class _Result:
            content = [_Text()]
            isError = False
        return _Result()

def make_client():
    c = MCPClient(FakeTransport())
    c._session = MockSession()
    c._initialized = True
    return c

# A) unit level
client = make_client()
cleaned = client._clean_tool_arguments({
    "query": "cats", "tags": [], "filters": {},
    "mixed": [{"opt": None}, 1], "label": "", "count": 0,
})
print("A cleaned =", cleaned)

# B) wire level
async def wire():
    c = make_client()
    await c.call_tool("search", {"query": "cats", "tags": []})
    print("B args on the wire =", c._session.sent[0][1])
    c2 = make_client()
    await c2.call_tool("search", {"query": "cats", "tags": ["a"]})
    print("B control non-empty =", c2._session.sent[0][1])

asyncio.run(wire())

E2E, real FastMCP stdio server with optional fields — server tool def search(query: str, tags: list | None = None, filters: dict | None = None) echoes back the exact arguments it received:

async def main():
    transport = StdioTransport(command=sys.executable, args=["echo_server.py"])
    async with MCPClient(transport) as client:
        res = await client.call_tool(
            "search", {"query": "cats", "tags": [], "filters": {}}
        )
        print("E2E server received:", res)

asyncio.run(main())

E2E, real FastMCP stdio server with tags required — server tool def search(query: str, tags: list[str]):

async def main():
    transport = StdioTransport(command=sys.executable, args=["mcp_server_required_tags.py"])
    async with MCPClient(transport) as client:
        res = await client.call_tool_result("search", {"query": "cats", "tags": []})
        print("explicit tags=[] -> is_error =", res.is_error)
        print("content:", res.content[0] if res.content else None)

asyncio.run(main())

Operating System

Other (specify in additional context) — macOS 26.6.2, arm64.

Python Version

3.12.14

crewAI Version

1.15.22 (editable install of main @ 4ed2abc7bbf504a634d3b733f2a97e0fbe8d44ec)

crewAI Tools Version

Not installed / not involved — the defect is in lib/crewai/src/crewai/mcp/client.py.

Virtual Environment

Venv (uv)

Evidence

Unit + wire levels (repro_clean_args.py), run on the commit above:

A cleaned           = {'query': 'cats', 'mixed': [1], 'label': '', 'count': 0}
A 'tags' present    = False
A 'filters' present = False
A 'mixed' value     = [1]
A 'label'/'count'   = '' 0
B tool called       = search
B args on the wire  = {'query': 'cats'}
B 'tags' on the wire = False
B control non-empty = {'query': 'cats', 'tags': ['a']}

E2E against a real FastMCP stdio server (optional tags/filters), same commit — the server echoes back the arguments it actually received:

E2E server received: {"query": "cats", "tags": null, "filters": null}
E2E control received: {"query": "cats", "tags": ["a"], "filters": {"k": "v"}}
E2E 'tags' key arrived:     False
E2E 'filters' key arrived:   False

E2E against a real FastMCP stdio server whose inputSchema declares tags required (server schema required: ['query', 'tags']) — the schema-valid call with an explicit empty list is rejected:

explicit tags=[]  -> is_error = True
content: Error executing tool search: 1 validation error for searchArguments
tags
  Field required [type=missing, input_value={'query': 'cats'}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.12/v/missing
control tags=['a'] -> is_error = False
content: RECEIVED query='cats' tags=['a']

Possible Solution

In _clean_tool_arguments, preserve explicitly empty containers and list positions: only drop a key when cleaning genuinely removed content (keep nested when the original value was already {}), and for lists keep one output element per non-None input element — clean dict items in place instead of dropping the ones that clean to empty, so indices do not shift. I am happy to open a PR with regression tests for []/{} arguments surviving and for list-position preservation — or happy to be assigned if you would rather scope it differently.

Additional context

  • Environment detail for the "Other" OS option: macOS 26.6.2, Apple silicon, Python 3.12.14, mcp 1.28.1, crewAI in a uv venv as an editable install of commit 4ed2abc7bbf504a634d3b733f2a97e0fbe8d44ec.
  • Reachability: every native MCP tool call goes through this path — Agent(mcps=[MCPServerStdio(...) | MCPServerHTTP(...)]) → MCPNativeTool._run_async (lib/crewai/src/crewai/tools/mcp_native_tool.py:129) → MCPClient.call_tool_result (lib/crewai/src/crewai/mcp/client.py:488) → _clean_tool_arguments. LLMs do emit explicit empty containers (e.g. tags: [] meaning "no filters"), so this affects any tool whose schema gives such a key a meaning.
  • Related issue/PR references found by collision checks: none. Searching this repo for _clean_tool_arguments and "empty tool arguments" returned no issue or PR covering this behaviour (the closest hit, PR fix: Bedrock tool calls extract empty arguments - uses wrong field name (#4748) #4750, is Bedrock tool-call argument extraction — an unrelated subsystem).
  • AI disclosure: this issue was authored by an AI agent (Claude Code). .github/CONTRIBUTING.md requires the llm-generated label on AI-authored issues; I attempted to apply it, but the API rejected the request (BlueX888 does not have the correct permissions to execute AddLabelsToLabelable), so a maintainer will need to add it. Disclosing here since I cannot set the label myself.

Activity

  1. added 5 commits that reference this issue on Oct 20, 2026
    c206b6c
    32e26fc
    08890ae
    b4cfcbb
    514e703
  2. github-actions commented on Nov 10, 2026

    @github-actions
    Contributor

    This issue is stale because it has been open for 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.

  3. github-actions commented on Nov 16, 2026

    @github-actions
    Contributor

    This issue was closed because it has been stalled for 5 days with no activity.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions