UAT: Tool model input_schema and output_schema are Optional (allow None) but spec requires them as mandatory fields #3665

New issue

Open

opened 2026-04-05 21:16:27 +00:00 by freemo · 0 comments

freemo commented

2026-04-05 21:16:27 +00:00

Owner

Metadata

Branch: fix/tool-input-output-schema-required
Commit Message: fix(domain/tool): make input_schema and output_schema required fields to match spec Tool UML
Milestone: None (Backlog)
Parent Epic: #392 (Epic: Actor YAML & Compiler)

Backlog note: This issue was discovered during autonomous operation
on milestone v3.7.0. It does not block milestone completion and has been
placed in the backlog for human review and future milestone assignment.

What Was Tested

Reviewed the Tool domain model in src/cleveragents/domain/models/core/tool.py and compared its input_schema and output_schema field definitions against the specification's Tool UML.

Expected Behavior (from spec)

Per docs/specification.md (Tool UML, line 21756-21757):

+ input_schema : JSONSchema
+ output_schema : JSONSchema

Both input_schema and output_schema are listed as required (non-optional) fields in the Tool UML. The spec describes a Tool as:

"Defined by JSON Schema inputs/outputs, capability metadata (read_only, writes, checkpointable), and a four-stage lifecycle"

The JSON Schema inputs/outputs are a core part of the Tool definition — they define the contract for how the tool is called and what it returns.

Actual Behavior (from code)

In src/cleveragents/domain/models/core/tool.py:

# Schemas
input_schema: dict[str, Any] | None = Field(
    default=None, description="JSON Schema for tool inputs"
)
output_schema: dict[str, Any] | None = Field(
    default=None, description="JSON Schema for tool outputs"
)

Both fields are typed as dict[str, Any] | None with default=None, making them optional. A Tool can be created without any input or output schema, which violates the spec's requirement that tools be "defined by JSON Schema inputs/outputs."

Impact

Spec non-compliance: Tools registered without schemas cannot be properly validated by callers or the tool execution framework.
Runtime errors: The tool execution layer may fail at runtime when trying to validate tool inputs/outputs if schemas are absent.
Actor graph issues: Actors that reference tools expect well-defined schemas for type-safe tool invocation.

Steps to Reproduce

from cleveragents.domain.models.core.tool import Tool, ToolSource
# This should fail validation but currently succeeds:
tool = Tool(
    name="local/my-tool",
    description="A tool without schemas",
    source=ToolSource.BUILTIN,
    # No input_schema or output_schema provided
)
assert tool.input_schema is None  # True — but should be rejected

Code Location

src/cleveragents/domain/models/core/tool.py, lines ~290-295

Suggested Fix

Change the field definitions to require schemas:

input_schema: dict[str, Any] = Field(
    ..., description="JSON Schema for tool inputs (required)"
)
output_schema: dict[str, Any] = Field(
    ..., description="JSON Schema for tool outputs (required)"
)

Note: If builtin source tools legitimately don't need schemas (because the runtime provides them), consider adding a model validator that requires schemas for non-builtin sources, or document the exception in the spec.

Subtasks

Investigate whether any ToolSource.BUILTIN tools legitimately omit schemas and document the exception if so
Change input_schema to dict[str, Any] with Field(...) (required, no default)
Change output_schema to dict[str, Any] with Field(...) (required, no default)
Update all existing tests that construct Tool instances to provide valid input_schema and output_schema values
Add a new Behave scenario verifying that Tool rejects construction without input_schema or output_schema for non-builtin sources
Run nox -e typecheck and nox -e unit_tests to confirm no regressions

Definition of Done

Tool.input_schema is required (non-optional) or has a documented exception for builtin tools
Tool.output_schema is required (non-optional) or has a documented exception for builtin tools
Existing tests updated to provide schemas when creating Tool instances
New behave test scenario verifies Tool rejects missing schemas for non-builtin sources
All nox stages pass
Coverage >= 97%

Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-new-issue-creator

## Metadata - **Branch**: `fix/tool-input-output-schema-required` - **Commit Message**: `fix(domain/tool): make input_schema and output_schema required fields to match spec Tool UML` - **Milestone**: None (Backlog) - **Parent Epic**: #392 (Epic: Actor YAML & Compiler) > **Backlog note:** This issue was discovered during autonomous operation > on milestone v3.7.0. It does not block milestone completion and has been > placed in the backlog for human review and future milestone assignment. ## What Was Tested Reviewed the `Tool` domain model in `src/cleveragents/domain/models/core/tool.py` and compared its `input_schema` and `output_schema` field definitions against the specification's Tool UML. ## Expected Behavior (from spec) Per `docs/specification.md` (Tool UML, line 21756-21757): ``` + input_schema : JSONSchema + output_schema : JSONSchema ``` Both `input_schema` and `output_schema` are listed as required (non-optional) fields in the Tool UML. The spec describes a Tool as: > "Defined by JSON Schema inputs/outputs, capability metadata (read_only, writes, checkpointable), and a four-stage lifecycle" The JSON Schema inputs/outputs are a core part of the Tool definition — they define the contract for how the tool is called and what it returns. ## Actual Behavior (from code) In `src/cleveragents/domain/models/core/tool.py`: ```python # Schemas input_schema: dict[str, Any] | None = Field( default=None, description="JSON Schema for tool inputs" ) output_schema: dict[str, Any] | None = Field( default=None, description="JSON Schema for tool outputs" ) ``` Both fields are typed as `dict[str, Any] | None` with `default=None`, making them optional. A `Tool` can be created without any input or output schema, which violates the spec's requirement that tools be "defined by JSON Schema inputs/outputs." ## Impact 1. **Spec non-compliance**: Tools registered without schemas cannot be properly validated by callers or the tool execution framework. 2. **Runtime errors**: The tool execution layer may fail at runtime when trying to validate tool inputs/outputs if schemas are absent. 3. **Actor graph issues**: Actors that reference tools expect well-defined schemas for type-safe tool invocation. ## Steps to Reproduce ```python from cleveragents.domain.models.core.tool import Tool, ToolSource # This should fail validation but currently succeeds: tool = Tool( name="local/my-tool", description="A tool without schemas", source=ToolSource.BUILTIN, # No input_schema or output_schema provided ) assert tool.input_schema is None # True — but should be rejected ``` ## Code Location - `src/cleveragents/domain/models/core/tool.py`, lines ~290-295 ## Suggested Fix Change the field definitions to require schemas: ```python input_schema: dict[str, Any] = Field( ..., description="JSON Schema for tool inputs (required)" ) output_schema: dict[str, Any] = Field( ..., description="JSON Schema for tool outputs (required)" ) ``` **Note**: If `builtin` source tools legitimately don't need schemas (because the runtime provides them), consider adding a model validator that requires schemas for non-builtin sources, or document the exception in the spec. ## Subtasks - [ ] Investigate whether any `ToolSource.BUILTIN` tools legitimately omit schemas and document the exception if so - [ ] Change `input_schema` to `dict[str, Any]` with `Field(...)` (required, no default) - [ ] Change `output_schema` to `dict[str, Any]` with `Field(...)` (required, no default) - [ ] Update all existing tests that construct `Tool` instances to provide valid `input_schema` and `output_schema` values - [ ] Add a new Behave scenario verifying that `Tool` rejects construction without `input_schema` or `output_schema` for non-builtin sources - [ ] Run `nox -e typecheck` and `nox -e unit_tests` to confirm no regressions ## Definition of Done - [ ] `Tool.input_schema` is required (non-optional) or has a documented exception for builtin tools - [ ] `Tool.output_schema` is required (non-optional) or has a documented exception for builtin tools - [ ] Existing tests updated to provide schemas when creating Tool instances - [ ] New behave test scenario verifies Tool rejects missing schemas for non-builtin sources - [ ] All nox stages pass - [ ] Coverage >= 97% --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-new-issue-creator

freemo added a new dependency

2026-04-05 21:16:40 +00:00

#392 Epic: Actor YAML & Compiler

freemo added this to the v3.7.0 milestone

2026-04-05 21:19:01 +00:00

freemo referenced this issue

2026-04-05 21:19:12 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3572

freemo referenced this issue

2026-04-05 21:20:57 +00:00

[Automated] CleverAgents Build Session - 2026-04-05 #3377

freemo referenced this issue