Skip to content

Python: Keep $defs at the root of wrapped MCP workflow tool schemas - #10367

Open
ni (nniiovoo) wants to merge 1 commit into
microsoft:mainfrom
nniiovoo:python-hosting-mcp-workflow-defs
Open

ni (nniiovoo) wants to merge 1 commit into
microsoft:mainfrom
nniiovoo:python-hosting-mcp-workflow-defs

Conversation

@nniiovoo

Copy link
Copy Markdown
Contributor

Motivation & Context

When WorkflowMCPTool wraps a non-object start input (like list[Item]) under properties.<argument_name>, the schema's $defs stayed inside the property while its #/$defs/... references point at the root. So the advertised inputSchema had references that don't resolve. Repro is in #10366.

Description & Review Guide

  • What are the major changes? _tool_for_workflow moves $defs from the wrapped schema to the root of the wrapper. If the wrapped schema has its own $id, it is a separate schema resource whose references already resolve inside it, so it is left as is.
  • What is the impact of these changes? In the inputSchema for wrapped inputs that use models (list[Model], Model | None, unions, recursive models), the #/$defs/... references now resolve. Object inputs and wrapped inputs without $defs are unchanged, and argument validation still goes through pydantic as before.
  • What do you want reviewers to focus on? The $id check. Pydantic only puts a $id there when the model sets one (e.g. through json_schema_extra), but moving $defs out of such a schema would break references that resolve today.

Tests: I added a test with a list[dataclass] input that validates arguments against the advertised schema with jsonschema (it fails on main), and one for a wrapped schema with its own $id.

Related Issue

Fixes #10366

AI Assistance

  • No material AI assistance was used.
  • This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: issue analysis, implementation, tests, and this description.

Contribution Checklist

  • The code builds clean without any errors or warnings
  • All unit tests pass, and I have added new tests where possible
  • The PR follows the Contribution Guidelines
  • This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
  • This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

Signed-off-by: NNIIOVO <haimingni44@gmail.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues block the fix for JSON Schema references in wrapped workflow inputs.

No open issues 🎉

What changed in this PR

Fixes #10366 by keeping JSON Schema references resolvable when WorkflowMCPTool wraps non-object workflow inputs.

Changes:

  • Moves $defs to the wrapper root so #/$defs/... references resolve.
  • Preserves nested definitions when the input schema has its own resource-defining $id.
  • Adds regression tests for schema validation, tool execution, and preservation of schemas with their own $id.
File Description
python/​packages/​hosting-mcp/​tests/​hosting_mcp/​test_workflow_tool.py Adds wrapped-input regression tests with and without a schema $id.
python/​packages/​hosting-mcp/​agent_framework_hosting_mcp/​_workflow_tool.py Relocates $defs when wrapping inputs while preserving separate schema resources.

Review effort: Balanced

@surlymochan Nick (surlymochan) left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-binding review (read the diff; not an approval).

What I verified:

  • The logic is sound: when a non-object input schema is wrapped, its $defs are hoisted to the new root, where the schema's #/$defs/... references point. When the schema carries its own $id (a separate resource), the $defs stay nested with it, so its references still resolve inside it.
  • The two new tests pin both branches: the wrapped list[WorkflowInput] case validates with jsonschema and executes end-to-end, and the $id case asserts $defs stays under properties.values.

Two questions:

  1. The code treats $id values of "" and "#" as "same document, hoist", but the tests only cover an absolute-URL $id. Is the "#" branch covered anywhere? A test for it would pin the allowlist.
  2. input_schema.pop("$defs", None) mutates the dict returned by input_adapter.json_schema(). Is that dict freshly built on every call, so the pop cannot leak into a cached/shared schema on a second list_tools() call?

This branch was successfully deployed

1 active deployment
github-app-auth — 65c7254d Deployed Nov 14, 2026 by nniiovoo via team_check #9488
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

python Usage: [Issues, PRs], Target: Python

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

3 participants