Tenant data model (DataPool)

Canonical DataPool schemas for a generic B2B value chain. Other model skills read and write these tables. This is a playbook for schema names, columns, and stop rules — not a prompt.

Document information

Field	Value
Canonical URL	`/docs/07_ai-agents-and-mcp/model_skills/00_shared/tenant-data-model`
Version (published date)	`2026-08-26`
Tags	`ai`, `skills`, `datapool`, `playbooks`

Kind

Resource / canonical model.

When to use

Install first. Stage playbooks and handovers depend on these schemas. Do not store value-chain records in platform Entities, products, or contracts unless the tenant already made that choice outside this library.

Depends on

None.

Prerequisites

id	question	search	if_missing_or_ambiguous	default_to_propose	binds_to
`leads_schema`	Which DataPool schema holds marketing leads?	Load `datapool`. `describe_datapool_table` with `schema_name` `leads` (and close aliases).	Ask to bind an existing name or create the suggested schema. Confirm before `create_datapool_schema`.	Create schema `leads` with the suggested columns below	Tenant `SKILL.md`
`opportunities_schema`	Which DataPool schema holds sales opportunities?	`describe_datapool_table` `opportunities`	Same as leads	Create `opportunities`	Tenant `SKILL.md`
`deliveries_schema`	Which DataPool schema holds delivery work?	`describe_datapool_table` `deliveries`	Same	Create `deliveries`	Tenant `SKILL.md`
`support_cases_schema`	Which DataPool schema holds support cases?	`describe_datapool_table` `support_cases`	Same	Create `support_cases`	Tenant `SKILL.md`
`handovers_schema`	Which DataPool schema holds inter-team handovers?	`describe_datapool_table` `handovers`	Same	Create `handovers`	Tenant `SKILL.md`

Import contract

Field	Value
`suggested_skill_id`	`tenant-data-model`
`version`	`1.0.0`
`capabilities.tools`	`describe_datapool_table`, `query_datapool`, `create_datapool_schema`, `insert_datapool_rows`, `update_datapool_rows`, `request_human_input`
Paired model agents	`sales-ready-lead-watcher`, `won-opportunity-handover-watcher`, `delivery-blocker-watcher`, `support-sla-watcher`

Suggested DataPool columns

Use these schema_definition objects when creating a missing schema (create_datapool_schema: schema_name + schema_definition). Confirm with request_human_input before create. If the tenant already has equivalent tables, bind names and map columns in the installed playbook — do not invent a second model.

leads

Column	Type	Required	Meaning
`lead_id`	string	yes	Stable id
`source`	string	no	Campaign or inbound source
`company_name`	string	yes	Account name as known to marketing
`contact_name`	string	no
`contact_email`	string	no
`status`	string	yes	`new` \| `qualifying` \| `sales_ready` \| `disqualified`
`score`	number	no	0–100
`disqualify_reason`	string	no	Required when status is `disqualified`
`owner_user_id`	string	no	Tenant user id
`updated_at`	string	no	ISO-8601 UTC

opportunities

Column	Type	Required	Meaning
`opportunity_id`	string	yes
`lead_id`	string	no	Originating lead
`company_name`	string	yes
`stage`	string	yes	`discovery` \| `proposal` \| `negotiation` \| `won` \| `lost`
`amount`	number	no
`currency`	string	no
`next_gate`	string	no	Quality gate not yet passed
`owner_user_id`	string	no
`close_date`	string	no
`lost_reason`	string	no	Required when `lost`
`updated_at`	string	no

deliveries

Column	Type	Required	Meaning
`delivery_id`	string	yes
`opportunity_id`	string	yes	Won opportunity
`status`	string	yes	`kickoff` \| `in_progress` \| `acceptance` \| `complete`
`kickoff_complete`	string	no	`yes` / `no`
`acceptance_complete`	string	no	`yes` / `no`
`blocker_summary`	string	no	Open quality-gate failure
`owner_user_id`	string	no
`updated_at`	string	no

support_cases

Column	Type	Required	Meaning
`case_id`	string	yes
`delivery_id`	string	no	Originating delivery
`severity`	string	yes	`sev1` \| `sev2` \| `sev3` \| `sev4`
`status`	string	yes	`open` \| `waiting_customer` \| `waiting_internal` \| `resolved` \| `closed`
`sla_due_at`	string	no	ISO-8601 UTC
`owner_user_id`	string	no
`updated_at`	string	no

handovers

Column	Type	Required	Meaning
`handover_id`	string	yes
`kind`	string	yes	`marketing_to_sales` \| `sales_to_delivery` \| `delivery_to_support`
`from_record_id`	string	yes	Source row id
`to_record_id`	string	no	Target row id after accept
`packet_json`	string	yes	DoD field packet as JSON text
`status`	string	yes	`proposed` \| `accepted` \| `rejected`
`notify_recipient_user_id`	string	yes	In-app inbox user
`notify_channel`	string	yes	Default `in_app_notification`
`notify_status`	string	no	`pending` \| `sent` \| `failed`
`accepted_at`	string	no
`updated_at`	string	no

Tenant SKILL.md (copy this body)

After Prerequisite binding, replace tokens.

# Tenant data model (DataPool)

Canonical value-chain records for this tenant live in DataPool. Load `load_platform_skill` with `skill_id: datapool`. Call `describe_datapool_table` before any row write.

Do not use platform Entities, products, or contracts as the system of record for this playbook.

## Bound schemas

| Role | schema_name |
|---|---|
| Leads | {{leads_schema}} |
| Opportunities | {{opportunities_schema}} |
| Deliveries | {{deliveries_schema}} |
| Support cases | {{support_cases_schema}} |
| Handovers | {{handovers_schema}} |

## Sequence

1. `describe_datapool_table` for the bound `schema_name`.
2. Read with `query_datapool`. Filter; do not scan unbounded.
3. Writes: `insert_datapool_rows` / `update_datapool_rows` using **only** columns from describe. Confirm before `delete_datapool_rows` or schema drops.
4. Status values must match the allowed enumerations in this playbook (or the bound tenant’s documented aliases).

## Stop

- Do not invent column names.
- Do not copy CRM-native keys into these rows (use `crm-field-mapping`).
- If describe fails, stop and report the missing schema; do not silently switch to another resource.

Optional skill.json

{
  "name": "tenant-data-model",
  "version": "1.0.0",
  "description": "Canonical DataPool schemas for the B2B value chain (leads through support).",
  "capabilities": {
    "prompt": ["Describe DataPool tables before writes. Bound schema_name values are the system of record."],
    "resources": [],
    "tools": [
      "describe_datapool_table",
      "query_datapool",
      "create_datapool_schema",
      "insert_datapool_rows",
      "update_datapool_rows",
      "request_human_input"
    ]
  }
}