Python: expose CodeAct tool parameter schemas

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Hyperlight and Monty currently list registered host-tool names in their CodeAct guidance but omit requiredness, types, parameter descriptions, enum values, and nested schema details. Models therefore lack enough information to reliably call tools unless developers repeat the contract in tool-level descriptions.

This change exposes that existing schema metadata while letting applications balance completeness and prompt size. It addresses the Python portion of #8125; the separate .NET work remains tracked in #8446.

Description & Review Guide

• What are the major changes? Added a private core helper that returns structured compact parameter metadata or the complete JSON Schema when compact rendering would be lossy. Added one tool_description_format option to the Hyperlight and Monty standalone tools and context providers. It accepts "compact", "json", or a per-tool mapping; compact is the default and missing mapping entries use compact. Both packages preserve configuration in run-scoped snapshots and serialized state, with Monty applying it to both tool descriptions and context instructions. Centralized format normalization and its shared type aliases in core so both integrations enforce identical validation and copy behavior. Raised the Hyperlight sandbox runtime stack to >=0.7.0,<0.8. Tests and package documentation cover rendering, fallback, validation, mapping copies, and lifecycle behavior.
• What is the impact of these changes? Simple scalar tools receive concise parameter contracts by default. Complex constraints automatically fall back to complete JSON Schema with an explicit note instead of silently losing metadata. Hyperlight now requires the 0.7 sandbox, WebAssembly backend, and Python guest packages. Sandbox execution, approvals, input schemas, caches, Monty type stubs, and runtime capabilities are otherwise unchanged.
• What do you want reviewers to focus on? Please review the conservative compact-schema eligibility rules and the single string-or-mapping API. Release follow-up: once the first core release containing the shared helpers is created, this PR must raise both Hyperlight and Monty's agent-framework-core minimum to that release before it is marked ready or published; the version has not yet been assigned, so this PR intentionally does not guess a dependency floor.

Related Issue

Closes #8445

Partially addresses #8125. The .NET portion remains open in #8446.

No other open PR was found for #8445.

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 is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• 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.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): df62c2a1a2ce
Model: gpt-5.6-sol-fast

Overview

The review found 2 verified inline finding(s).

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
2 verified findings remained after source verification (1 high, 1 medium) across 2 files. Details are attached to the affected lines below.

Affected areas: python/packages/core/agent_framework/_tools.py, python/packages/hyperlight/agent_framework_hyperlight/_instructions.py

[Copilot]

🟡 Changes recommended

Hyperlight and Monty must raise their core dependency minimum to a release containing the imported helper before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds configurable compact or full JSON parameter-schema descriptions for CodeAct tools in Hyperlight and Monty, backed by a shared core formatter.

Changes:

• Added shared schema formatting with compact rendering and JSON fallback.
• Added tool_description_format configuration, snapshots, and serialization.
• Added tests and documentation for rendering, validation, and lifecycle behavior.

File summaries

File	Description
python/packages/monty/tests/monty/test_monty_codeact.py	Monty CodeAct behavior tests
python/packages/monty/README.md	Monty usage documentation
python/packages/monty/AGENTS.md	Monty API guidance
python/packages/monty/agent_framework_monty/_provider.py	Monty provider wiring
python/packages/monty/agent_framework_monty/_instructions.py	Monty schema rendering
python/packages/monty/agent_framework_monty/_execute_code_tool.py	Monty configuration and state wiring
python/packages/hyperlight/tests/hyperlight/test_hyperlight_codeact.py	Hyperlight behavior tests
python/packages/hyperlight/README.md	Hyperlight usage documentation
python/packages/hyperlight/agent_framework_hyperlight/_provider.py	Hyperlight provider wiring
python/packages/hyperlight/agent_framework_hyperlight/_instructions.py	Hyperlight schema rendering
python/packages/hyperlight/agent_framework_hyperlight/_execute_code_tool.py	Hyperlight configuration and state wiring
python/packages/core/tests/core/test_tools.py	Formatter regression tests
python/packages/core/AGENTS.md	Core helper guidance
python/packages/core/agent_framework/_tools.py	Shared parameter formatter

Review details

• Files reviewed: 14/14 changed files
• Comments generated: 2
• Review effort level: Lite (auto)

Note

Copilot is running an experiment and ran this review at Lite.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 2

Result: Findings reported
Scope: 3 net-new commit(s): 19934609925b, a994bb920987, fb065891ed84
Model: gpt-5.6-sol-fast

Overview

The incremental changes successfully centralize format validation and preserve detached configuration across both integrations, with focused validation and copy-behavior tests. However, the Hyperlight 0.7 dependency upgrade introduces backend filesystem quotas without wiring the package's existing configurable output limits into the sandbox, so documented raised limits no longer work.

Reviewed the supplied incremental change set across correctness, security/reliability, architecture, and failure behavior.
1 verified finding remained after source verification (1 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/hyperlight/pyproject.toml