Tool.to_mcp_schema() includes 'kind' field in properties which should not be sent to LLMs

[xingyaoww]

Problem

The Tool.to_mcp_schema() method outputs a MCP schema where the "properties" field contains a kind field. This kind field should NOT be included in tool schemas sent to LLMs, as it's an internal discriminator field used by Pydantic for polymorphism.

Current Behavior

When calling Action.to_mcp_schema() on any Action subclass, the resulting schema includes kind in its properties:

from openhands.sdk.tool.schema import Action
from pydantic import Field

class TestAction(Action):
    """Test action class."""
    command: str = Field(description="Command to execute")

schema = TestAction.to_mcp_schema()
print(schema["properties"].keys())
# Output: dict_keys(['kind', 'command'])

Full schema output:

{
  "type": "object",
  "description": "Test action class.",
  "properties": {
    "kind": {
      "type": "string"
    },
    "command": {
      "type": "string",
      "description": "Command to execute"
    }
  },
  "required": [
    "command"
  ]
}

The kind field should not be present in the schema sent to LLMs.

Root Cause

1. Action inherits from Schema and DiscriminatedUnionMixin
2. DiscriminatedUnionMixin defines a kind field as a Pydantic field: kind: str = Field(default="")
3. The to_mcp_schema() method uses model_json_schema() which includes all Pydantic fields, including kind
4. The _process_schema_node() function processes the schema but doesn't filter out the kind field

Proposed Solution

We should modify the schema generation to exclude the kind field from the MCP schema output. The recommended approach involves two changes:

1. Update Schema.to_mcp_schema() to exclude kind

In openhands/sdk/tool/schema.py, modify the to_mcp_schema() method to filter out the kind field:

@classmethod
def to_mcp_schema(cls) -> dict[str, Any]:
    """Convert to JSON schema format compatible with MCP."""
    full_schema = cls.model_json_schema()
    # Process the schema to simplify and resolve $ref
    result = _process_schema_node(full_schema, full_schema.get("$defs", {}))
    
    # Remove 'kind' from properties if present (discriminator field, not for LLM)
    if "properties" in result and "kind" in result["properties"]:
        result["properties"].pop("kind")
        # Also remove from required if present
        if "required" in result and "kind" in result["required"]:
            result["required"].remove("kind")
    
    return result

2. Refactor Schema to directly inherit from DiscriminatedUnionMixin

Currently, Action and Observation inherit from both Schema and DiscriminatedUnionMixin. We could simplify this by having Schema directly inherit from DiscriminatedUnionMixin:

class Schema(DiscriminatedUnionMixin):
    """Base schema for input action / output observation."""
    
    model_config = ConfigDict(extra="forbid", frozen=True)
    
    # ... rest of the implementation

This would make it clearer that all schemas have the kind discriminator, and it would be natural to exclude it in the to_mcp_schema() method within the same class.

Benefits

1. Cleaner LLM schemas: LLMs won't see the internal kind discriminator field
2. Better separation of concerns: Keep kind as a Pydantic field for internal use, but exclude it from external schemas
3. Simpler inheritance hierarchy: Having Schema inherit from DiscriminatedUnionMixin makes the relationship explicit

Testing

After implementation, verify:

1. The kind field is excluded from all MCP schemas generated by to_mcp_schema()
2. The kind field still works correctly for Pydantic validation and discriminated unions
3. All existing tests pass
4. Tool schemas sent to LLMs (via to_openai_tool() and to_responses_tool()) don't include kind

Files to Modify

• openhands/sdk/tool/schema.py - Update Schema class and to_mcp_schema() method
• Tests in tests/sdk/tool/ - Add tests to verify kind is excluded from MCP schemas

[openhands-ai]

I'm on it! xingyaoww can track my progress at all-hands.dev

[openhands-ai]

Summary

I've successfully fixed issue #640 by removing the 'kind' field from MCP schema output. Here's what was accomplished:

✅ Changes Made

1. Core Fix (openhands/sdk/tool/schema.py)

• Modified Schema.to_mcp_schema() method to filter out the kind field from:
  • The properties dictionary
  • The required list (if present)
• The fix is minimal (10 lines) and preserves the kind field for internal Pydantic discriminated union functionality

2. Comprehensive Test Suite (tests/sdk/tool/test_mcp_schema.py)

• Created 6 test cases covering:
  • Basic Action schema excludes 'kind'
  • Complex Action with multiple field types excludes 'kind'
  • Observation schema excludes 'kind'
  • 'kind' still works correctly for discriminated unions (internal use)
  • 'kind' is removed from required fields list
  • Schema structure remains valid after exclusion

✅ Verification

Before Fix:

schema = TestAction.to_mcp_schema()
# Properties: ['kind', 'command']  ❌ 'kind' exposed to LLMs

After Fix:

schema = TestAction.to_mcp_schema()
# Properties: ['command']  ✅ 'kind' hidden from LLMs

All Tests Pass:

• ✅ All 6 new tests in test_mcp_schema.py pass
• ✅ All 77 existing tests in tests/sdk/tool/ pass
• ✅ Pre-commit hooks pass (ruff format, ruff lint, pycodestyle, pyright)

🔗 Pull Request

PR #641 Created: #641

• Branch: openhands/fix-kind-field-in-mcp-schema
• Status: Ready for review
• Fixes: Tool.to_mcp_schema() includes 'kind' field in properties which should not be sent to LLMs #640
• All requirements from the issue have been addressed

The fix ensures that LLMs receive clean schemas without internal Pydantic discriminator fields while maintaining full backward compatibility.

_{View full conversation}