cleveragents-core/docs/reference/tool_model.md

Tool & Validation Domain Models

The Tool and Validation domain models are defined in src/cleveragents/domain/models/core/tool.py.

Overview

Model	Purpose
Tool	Atomic unit of execution — namespaced, independently registered callable operation
Validation	Extends Tool with pass/fail semantics — always read-only, never writes, never checkpointable

Key classes

• ToolSource — enum: mcp, agent_skill, builtin, custom, wrapped
• ToolType — enum: tool, validation
• ValidationMode — enum: required, informational
• ToolCapability — capability metadata (read_only, writes, checkpointable, side_effects, etc.)
• ResourceSlot — typed resource binding declaration
• ToolLifecycle — optional lifecycle hooks (discover, activate, deactivate)

Factory methods

• Tool.from_config(config) — create a Tool from a YAML configuration dict
• Validation.from_config(config) — create a Validation from a YAML configuration dict

Serialization

• tool.as_cli_dict() — stable-ordered dictionary for CLI rendering

Testing

Behave BDD tests (unit tests)

The primary test suite lives in features/tool_model.feature with step definitions in features/steps/tool_model_steps.py.

Run with nox:

nox -s unit_tests -- features/tool_model.feature

The Behave suite covers:

• Tool/Validation model creation and field validation
• Source-conditional field requirements
• Capability constraint enforcement
• ResourceSlot binding validation
• from_config() loading (including YAML example files)
• as_cli_dict() output stability
• Enum value completeness

Robot Framework smoke tests

The Robot smoke suite in robot/tool_model.robot provides integration-level smoke tests that verify the same model creation and YAML loader outputs through a subprocess helper (robot/helper_tool_model.py).

Run with nox:

nox -s integration_tests -- robot/tool_model.robot

Or directly with Robot Framework:

robot --outputdir build/reports/robot robot/tool_model.robot

The Robot suite covers:

Test Case	What it verifies
Create Minimal Tool Model	Builtin tool creation, identity fields
Create Validation Model With Forced Constraints	Validation read_only/writes/checkpointable forcing
Load Custom Tool From YAML Config	Tool.from_config() with examples/tools/custom-tool.yaml
Load MCP Tool From YAML Config	Tool.from_config() with examples/tools/mcp-tool.yaml
Load Wrapped Validation From YAML Config	Validation.from_config() with examples/validations/wrapped-validation.yaml
Load Required Validation From YAML Config	Validation.from_config() with examples/validations/required-validation.yaml
Validate Forced Constraints On Writable Capability	Validation forces read_only even with writable capability
Reject Invalid Tool Configurations	Invalid name, missing code, conflicting capabilities rejected

ASV benchmarks

Performance benchmarks live in benchmarks/tool_model_bench.py:

nox -s benchmark