# 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