cleveragents-core/docs/reference/database_schema.md

Database Schema Reference

This document describes the database tables used by the CleverAgents tool and validation registry, introduced in migration c1_001_tool_registry.

Tables

tools

Stores registered tool and validation definitions.

Column	Type	Constraints	Description
tool_id	TEXT	PRIMARY KEY	ULID identifier
name	TEXT	NOT NULL, UNIQUE	Namespaced name (namespace/short_name)
description	TEXT		Human-readable description
tool_type	TEXT	NOT NULL, CHECK (tool/validation)	Discriminator for registry queries
source_type	TEXT	NOT NULL, CHECK (see below)	Implementation source
input_schema	TEXT		JSON Schema for tool inputs
output_schema	TEXT		JSON Schema for tool outputs
read_only	BOOLEAN	NOT NULL, DEFAULT FALSE	Tool only reads, never writes
writes	BOOLEAN	NOT NULL, DEFAULT FALSE	Tool can write to resources
checkpointable	BOOLEAN	NOT NULL, DEFAULT FALSE	Tool supports checkpoint/rollback
side_effects	BOOLEAN	NOT NULL, DEFAULT FALSE	Tool has known side effects
config_yaml	TEXT		Raw YAML config for reconstruction
created_at	TEXT	NOT NULL	ISO-8601 timestamp
updated_at	TEXT	NOT NULL	ISO-8601 timestamp

Check constraints:

• ck_tools_tool_type: tool_type IN ('tool', 'validation')
• ck_tools_source_type: source_type IN ('mcp', 'agent_skill', 'builtin', 'custom', 'wrapped')

Indexes:

• ix_tools_name on (name)
• ix_tools_tool_type on (tool_type)

---

tool_bindings

Stores resource slot bindings for tools.

Column	Type	Constraints	Description
binding_id	TEXT	PRIMARY KEY	ULID identifier
tool_id	TEXT	NOT NULL, FK → tools.tool_id CASCADE	Parent tool reference
slot_name	TEXT	NOT NULL	Named resource slot
resource_type	TEXT	NOT NULL	Expected resource type
binding_mode	TEXT	NOT NULL, CHECK (see below)	How the slot is resolved
access_level	TEXT	NOT NULL, DEFAULT read_only	Access level on bound resource
created_at	TEXT	NOT NULL	ISO-8601 timestamp

Check constraints:

• ck_tool_bindings_mode: binding_mode IN ('context', 'static', 'parameter')
• ck_tool_bindings_access: access_level IN ('read_only', 'read_write')

Unique constraints:

• uq_tool_bindings_tool_slot: UNIQUE(tool_id, slot_name)

---

validation_attachments

Links validations to resources with mode semantics.

Column	Type	Constraints	Description
attachment_id	TEXT	PRIMARY KEY	ULID identifier
resource_id	TEXT	NOT NULL, FK → resources.resource_id CASCADE	Target resource
validation_name	TEXT	NOT NULL	References tools.name (validation)
mode	TEXT	NOT NULL, DEFAULT required	required or informational
created_at	TEXT	NOT NULL	ISO-8601 timestamp

Check constraints:

• ck_validation_attachments_mode: mode IN ('required', 'informational')

Unique constraints:

• uq_validation_attachments_resource_validation: UNIQUE(resource_id, validation_name)

Indexes:

• ix_validation_attachments_resource_id on (resource_id)

---

Relationships

tools 1 ──< tool_bindings       (tool_id FK, CASCADE delete)
resources 1 ──< validation_attachments  (resource_id FK, CASCADE delete)
validation_attachments.validation_name → tools.name (logical, not enforced by FK)

Migration

• Revision: c1_001_tool_registry
• Depends on: b0_001_projects
• File: alembic/versions/c1_001_tool_registry.py