fix: update MergeAgentHandlerTool to rightly handle MCP protocol by mplacona · Pull Request #4255 · crewAIInc/crewAI

mplacona · 2026-01-20T16:12:46Z

Disclosure: I worked with Merge on getting this PR together

Problem

The MergeAgentHandlerTool was not correctly handling the Agent Handler MCP protocol's parameter format:

Agent Handler wraps all parameters in an input object
MCP protocol uses inputSchema instead of parameters for tool schemas
Schema parsing didn't handle anyOf nullable type definitions
Pydantic schema exposed the wrapper object instead of actual parameters

This caused tools to fail when called by CrewAI agents.

Solution

Parameter Wrapping

Wrap all arguments in an {"input": kwargs} structure before sending to Agent Handler
Add backwards compatibility to detect pre-wrapped input and pass through as-is

Schema Parsing

Updated to parse inputSchema from MCP responses (not parameters)
Automatically unwrap the input object to expose actual tool parameters in Pydantic schema
This ensures CrewAI agents see the real parameters (e.g., title, description) instead of just input

Nullable Type Support

Added support for anyOf type definitions commonly used for nullable fields
Properly marks nullable fields as optional with None default values
Correctly infers the primary type from anyOf definitions

Debugging Improvements

Added debug logging when inputSchema is missing from responses
Better error messages for schema parsing failures

Testing

Updated all test mocks to use inputSchema format matching real MCP responses
Added tests for schema parsing from inputSchema
Added tests for anyOf nullable type handling
Added tests for backwards compatibility with pre-wrapped input
Verified all tests pass with new parameter wrapping logic

Impact

Tools now work correctly with Agent Handler MCP protocol
Pydantic schemas correctly represent actual tool parameters
CrewAI agents can properly invoke Agent Handler tools
Backwards compatible with any existing code that pre-wraps parameters

Note

Medium Risk
Changes affect how all Agent Handler tool calls are serialized and how Pydantic argument schemas are inferred, which can break integrations if assumptions differ from real MCP responses. Coverage is strong, but runtime behavior depends on external schema variations.

Overview
Fixes MergeAgentHandlerTool to match Agent Handler’s MCP protocol by wrapping tool call arguments under input (with pass-through support for legacy pre-wrapped calls) and by parsing tool schemas from inputSchema instead of parameters.

Schema generation now unwraps the top-level input object so args_schema exposes real tool parameters, and adds handling for nullable JSON Schema definitions via anyOf (including keeping required-but-nullable fields required). Tests were updated to use inputSchema, assert input-wrapped requests, and add coverage for nullable/required/optional schema edge cases and backwards-compat behavior.

^{Written by Cursor Bugbot for commit ab16c4b. This will update automatically on new commits. Configure here.}

…l correctly ## Problem The MergeAgentHandlerTool was not correctly handling the Agent Handler MCP protocol's parameter format: 1. Agent Handler wraps all parameters in an `input` object 2. MCP protocol uses `inputSchema` instead of `parameters` for tool schemas 3. Schema parsing didn't handle `anyOf` nullable type definitions 4. Pydantic schema exposed the wrapper object instead of actual parameters This caused tools to fail when called by CrewAI agents. ## Solution ### Parameter Wrapping - Wrap all arguments in an `{"input": kwargs}` structure before sending to Agent Handler - Add backwards compatibility to detect pre-wrapped input and pass through as-is ### Schema Parsing - Updated to parse `inputSchema` from MCP responses (not `parameters`) - Automatically unwrap the `input` object to expose actual tool parameters in Pydantic schema - This ensures CrewAI agents see the real parameters (e.g., `title`, `description`) instead of just `input` ### Nullable Type Support - Added support for `anyOf` type definitions commonly used for nullable fields - Properly marks nullable fields as optional with `None` default values - Correctly infers the primary type from `anyOf` definitions ### Debugging Improvements - Added debug logging when `inputSchema` is missing from responses - Better error messages for schema parsing failures ## Testing - Updated all test mocks to use `inputSchema` format matching real MCP responses - Added tests for schema parsing from `inputSchema` - Added tests for `anyOf` nullable type handling - Added tests for backwards compatibility with pre-wrapped input - Verified all tests pass with new parameter wrapping logic ## Impact - Tools now work correctly with Agent Handler MCP protocol - Pydantic schemas correctly represent actual tool parameters - CrewAI agents can properly invoke Agent Handler tools - Backwards compatible with any existing code that pre-wraps parameters

gilfeig

LGTM!

Separate nullable type annotation from optional default value in schema parsing. Previously, required nullable fields were incorrectly given a None default, allowing callers to omit them. This caused API errors when backends distinguish between missing fields and explicit null values. Changes: - Split nullable (type accepts None) from optional (has default) - Required nullable fields now require explicit value (can be None) - Improve input parameter wrapping check with isinstance guard - Add comprehensive tests for all field type combinations All 27 tests pass, confirming fix works without breaking existing functionality.

lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py

mplacona · 2026-02-03T12:06:20Z

@lorenzejay could you please help me get this past the finish line? Thanks

lorenzejay · 2026-02-11T18:17:17Z

any chance you can send a loom video of this working or help me build a way to test this out?

lorenzejay · 2026-02-11T18:21:10Z

lib/crewai-tools/tests/tools/merge_agent_handler_tool_test.py

                    "name": "linear__create_issue",
                    "description": "Creates a new issue in Linear",
-                    "parameters": {
+                    "inputSchema": {


function calling expects paramters. Why are we changing this to inputScheme?

cursor

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

This PR is being reviewed by Cursor Bugbot

Details

Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.

To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

cursor · 2026-02-11T18:21:51Z

lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py

+                                        elif json_type == "array":
+                                            field_type = list[Any]
+                                        elif json_type == "object":
+                                            field_type = dict[str, Any]


Duplicated JSON-to-Python type mapping logic blocks

Low Severity

The JSON schema type-to-Python type mapping logic (mapping "string" → str, "integer" → int, etc.) is fully duplicated: once inside the anyOf branch and once in the else branch. Extracting this into a small helper function or dict lookup would reduce the maintenance burden and ensure any future type mapping changes are applied consistently in both paths.

gilfeig approved these changes Jan 20, 2026

View reviewed changes

This comment was marked as outdated.

Sign in to view

cursor bot reviewed Jan 20, 2026

View reviewed changes

lib/crewai-tools/src/crewai_tools/tools/merge_agent_handler_tool/merge_agent_handler_tool.py Show resolved Hide resolved

mplacona and others added 7 commits January 21, 2026 16:44

Merge branch 'main' into main

f968980

Merge branch 'main' into main

7cbd89e

Merge branch 'main' into main

6495246

Merge branch 'main' into main

683b33a

Merge branch 'main' into main

f9c9239

Merge branch 'main' into main

71a1891

Merge branch 'main' into main

e88a5d9

lorenzejay approved these changes Feb 2, 2026

View reviewed changes

Merge branch 'main' into main

e415a87

Merge branch 'main' into main

ab16c4b

lorenzejay reviewed Feb 11, 2026

View reviewed changes

cursor bot reviewed Feb 11, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Comments

fix: update MergeAgentHandlerTool to rightly handle MCP protocol#4255

fix: update MergeAgentHandlerTool to rightly handle MCP protocol#4255
mplacona wants to merge 11 commits intocrewAIInc:mainfrom
mplacona:main

mplacona commented Jan 20, 2026 •

edited by cursor bot

Loading

Uh oh!

gilfeig left a comment

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

mplacona commented Feb 3, 2026

Uh oh!

lorenzejay commented Feb 11, 2026

Uh oh!

lorenzejay Feb 11, 2026

Uh oh!

cursor bot left a comment

Uh oh!

cursor bot Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Comments

Conversation

mplacona commented Jan 20, 2026 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

Parameter Wrapping

Schema Parsing

Nullable Type Support

Debugging Improvements

Testing

Impact

Uh oh!

gilfeig left a comment

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

Uh oh!

mplacona commented Feb 3, 2026

Uh oh!

lorenzejay commented Feb 11, 2026

Uh oh!

lorenzejay Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

This PR is being reviewed by Cursor Bugbot

Uh oh!

cursor bot Feb 11, 2026

Choose a reason for hiding this comment

Duplicated JSON-to-Python type mapping logic blocks

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mplacona commented Jan 20, 2026 •

edited by cursor bot

Loading