cleveragents-core/docs/reference/tool_model.md

Tool Domain Model

The Tool is the atomic unit of execution in CleverAgents -- a namespaced, independently registered callable operation.

Tool Name

Tools use a namespace/short_name naming pattern:

local/line-counter
devops/docker-build

The name is the unique identifier. Tools and Validations share the same namespace; no collisions are allowed.

Source Types

Source	Description	Required Fields
mcp	Delegates to an MCP server	mcp_server, mcp_tool_name
agent_skill	Agent Skills Standard folder	agent_skill_path
builtin	Provided by the runtime	(none)
custom	Inline Python code	code
wrapped	Validation-only; wraps an existing tool	(set via Validation)

ToolCapability

Describes what a tool can and cannot do:

Field	Type	Default	Description
read_only	bool	False	Tool only reads, never writes
writes	bool	False	Tool can write to resources
write_scope	str | None	None	Scope of writes
checkpointable	bool	False	Tool supports checkpoint/rollback
checkpoint_scope	CheckpointScope | None	None	Granularity of checkpoint support
side_effects	list[str]	[]	Known side effects
idempotent	bool	False	Safe to re-run
unsafe	bool	False	Requires extra safety checks
human_approval_required	bool	False	Requires human approval
cost_profile	str | None	None	Named cost profile

Constraint: If read_only=True, then writes and checkpointable must be False.

ResourceSlot

Declares a resource binding for a tool:

Field	Type	Default	Description
name	str	(required)	Slot name (valid Python identifier)
resource_type	str	(required)	Resource type name
access	ResourceAccessMode	(required)	read_only or read_write
description	str	""	Human-readable description
binding	BindingMode	contextual	How the resource is resolved
static_resource	str | None	None	Resource name (required for static)
required	bool	True	Whether slot must be filled

Constraint: static_resource required when binding=static; forbidden otherwise.

ToolLifecycle

Optional lifecycle hooks:

Field	Type	Description
discover	str | None	Hook for tool discovery
activate	str | None	Hook for tool activation
deactivate	str | None	Hook for tool deactivation

Tool Fields

Field	Type	Default	Description
name	str	(required)	namespace/short_name format
description	str	(required)	Short description
source	ToolSource	(required)	Implementation source
tool_type	ToolType	tool	Registry discriminator
code	str | None	None	Inline Python (custom source)
mcp_server	str | None	None	MCP server name
mcp_tool_name	str | None	None	MCP tool name
agent_skill_path	str | None	None	Agent Skills path
input_schema	dict | None	None	JSON Schema for inputs
output_schema	dict | None	None	JSON Schema for outputs
capability	ToolCapability	ToolCapability()	Capability metadata
resource_slots	list[ResourceSlot]	[]	Resource bindings
lifecycle	ToolLifecycle | None	None	Lifecycle hooks
timeout	int	300	Execution timeout (seconds, >= 1)

Class Methods

• Tool.from_config(config: dict) -- Create from a YAML config dict
• tool.as_cli_dict() -- Stable ordered dict for CLI rendering

Properties

• tool.namespace -- Extracted namespace from name
• tool.short_name -- Extracted short name from name