Skip to content

Python: [Bug]: WorkflowMCPTool input schema has $ref pointers that don't resolve for wrapped inputs like list[Model] #10366

Description

@nniiovoo

Observed Behavior

When a workflow's start input isn't an object (for example list[Item] or Item | None), WorkflowMCPTool wraps the input schema under properties.<argument_name>. The schema's $defs stay inside that property, but its references still point at the root (#/$defs/Item). So the inputSchema the MCP server advertises has references that don't resolve, and anything that resolves them, like a JSON Schema validator, fails on it.

The tool call itself still works, because the server validates the arguments with pydantic.

Expected Behavior

$defs stays at the root of the wrapped schema, so #/$defs/... references resolve.

Steps to Reproduce

  1. Build a workflow whose start executor takes list[SomeDataclass]
  2. Wrap it in WorkflowMCPTool and call list_tools()
  3. Validate arguments against the returned input_schema

Minimal Reproduction

import asyncio
from dataclasses import dataclass

import jsonschema
from agent_framework import WorkflowBuilder, WorkflowContext, executor

from agent_framework_hosting_mcp import WorkflowMCPTool


@dataclass
class Item:
    name: str
    qty: int


@executor(id="count")
async def count(items: list[Item], ctx: WorkflowContext[object, str]) -> None:
    await ctx.yield_output(str(sum(item.qty for item in items)))


async def main():
    workflow = WorkflowBuilder(start_executor=count, name="count", output_from=[count]).build()
    tool = WorkflowMCPTool(workflow, argument_name="items")

    schema = (await tool.list_tools()).tools[0].input_schema
    print("root keys:", sorted(schema))
    print("items keys:", sorted(schema["properties"]["items"]))
    jsonschema.validate({"items": [{"name": "a", "qty": 2}]}, schema)
    print("schema is valid")


asyncio.run(main())

Error Messages and Stack Traces

root keys: ['additionalProperties', 'properties', 'required', 'type']
items keys: ['$defs', 'items', 'type']
...
jsonschema.exceptions._WrappedReferencingError: PointerToNowhere: '/$defs/Item' does not exist within {'type': 'object', 'properties': {'items': {'$defs': {'Item': {...}}, 'items': {'$ref': '#/$defs/Item'}, 'type': 'array'}}, ...}

Package Versions

agent-framework-core 1.26.0, agent-framework-hosting-mcp 1.0.0a261106 (main at 92838b6), mcp 2.3.0, jsonschema 4.26.0

Python Version

Python 3.12

Operating System

macOS

Regression

No

Additional Context

The wrapping is in _tool_for_workflow in _workflow_tool.py. A fix could be to move $defs from the wrapped schema to the root of the wrapper. I have a fix with a test and will open a PR.

AI assistance: I used an AI assistant to help find the cause and write this up. I ran the repro myself.

Acknowledgements

  • I searched existing issues and did not find a duplicate.
  • I personally verified this behavior and the reproduction details are authentic.

Activity

  1. added
    pythonUsage: [Issues, PRs], Target: Python
    triageUsage: [Issues], Target: All issues that still need to be triaged
    on Nov 14, 2026
  2. added
    reproducedUsage: [Issues], Target: all issues that can be reproduced by the triage workflow
    on Nov 14, 2026
  3. github-actions commented on Nov 14, 2026

    @github-actions
    Contributor

    Reproduced on main (92838b6) using the reporter's scenario, rebuilt independently: WorkflowMCPTool.list_tools() for a list[Item] start input returns a schema with $defs nested under properties.items, while $ref stays #/$defs/Item. jsonschema.validate then fails with PointerToNowhere: '/$defs/Item'. The cause is the wrapping in _tool_for_workflow (python/packages/hosting-mcp/.../_workflow_tool.py). Fix PR #10367 is open and not merged.

    Support boundary: unclear. I didn't find a maintained spec or decision record that sets it, so scope is left to maintainers. Reproduction does not imply acceptance or priority.

    Evidence: https://github.com/microsoft/agent-framework/actions/runs/43637113690

    Generated by Issue Routing for #10366 · copilot · auto · ~24 AIC · ⌖ ~1 AIC · ⊞ 5.2K · ◷

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

Metadata

Metadata

Labels

pythonUsage: [Issues, PRs], Target: PythonreproducedUsage: [Issues], Target: all issues that can be reproduced by the triage workflowtriageUsage: [Issues], Target: All issues that still need to be triaged

Type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions