Skip to content

monte-carlo-data/mc-agent-toolkit / skills/monitoring-advisor

monte-carlo-monitoring-advisor

Verified

Analyze data coverage, create monitors for warehouse tables and AI agents. Covers coverage gaps, use-case analysis, data monitor creation, and agent observability.

references/data-table-monitor.md

View on GitHub
# Table Monitor Reference

Detailed reference for building `create_or_update_table_monitor` tool calls. The tool follows the **two-call preview-then-confirm pattern** — see `data-monitor-creation.md` for the full flow.

## Critical Constraints

- **NEVER guess column names.** Always verify table and schema names from `get_asset` or `search` before building the asset selection.
- **`alert_conditions` is a flat list of strings** — metric names like `"last_updated_on"`, `"schema"`, `"total_row_count"`. NEVER pass dicts like `{"metric": "last_updated_on", "operator": "AUTO"}`. That shape is rejected with `Input should be a valid string [type=string_type, input_value={'metric': '...', 'operator': 'AUTO'}]`. Table monitors do not take per-condition operators — they use anomaly detection on the named metrics by default.

---

## When to Use

Use a table monitor when the user wants to:

- Monitor many tables at once across an entire database or schema
- Track freshness (when was each table last updated?)
- Detect schema changes (columns added, removed, or type-changed)
- Monitor volume changes (row count anomalies) across a broad set of tables
- Apply broad coverage with anomaly detection (no custom thresholds needed)

**Do NOT use a table monitor when the user wants to:**

- Track field-level metrics on a single table (use a metric monitor)
- Apply custom thresholds or explicit operators like GT/LT (use a metric monitor)
- Validate row-level business rules or referential integrity (use a validation monitor)

---

## Required Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `name` | string | Unique identifier for the table monitor. Must be unique across all table monitors in the same namespace. |
| `description` | string | Human-readable description of what the monitor checks (max 512 characters). |
| `warehouse` | string | Warehouse name or UUID. Use `get_asset` or `search` to find it. |
| `asset_selection` | object | Asset selection config defining which tables to monitor (see Asset Selection below). |

## Optional Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `alert_conditions` | array of strings | `["last_updated_on", "schema", "total_row_count", "total_row_count_last_changed_on"]` | Metric names to monitor (see Alert Conditions below). |
| `domain_uuids` | array of string (uuid) | none | Domain UUIDs (use `get_domains` to list). Data monitors accept exactly one UUID in the list. |
| `audiences` | array of string | none | Notification audience **names** (not UUIDs) to alert when the monitor triggers. |
| `failure_audiences` | array of string | none | Notification audience names to alert on query execution failures. |
| `notes` | string | none | Free-text notes shown in the UI (separate from `description`). |
| `priority` | string | none | Monitor priority (e.g. `"P1"`, `"P2"`). |
| `tags` | array of `{name, value}` | none | Key-value tags to attach. |
| `is_draft` | bool | `False` | When `True`, saves the monitor as a draft (not active). |
| `monitor_uuid` | string (uuid) | none | UUID of an existing monitor to update in place. Omit to create a new monitor. **PUT semantics:** the call fully replaces the monitor's configuration — fields you omit revert to tool defaults, they are NOT left untouched. Before editing, read the current config with `get_monitors(monitor_ids=[<uuid>], include_fields=["config"])` and re-pass every field you want to keep. See `data-monitor-creation.md` (Step 7) for the safe-edit workflow. |
| `dry_run` | bool | `True` | Preview mode. When omitted or `True`, returns YAML preview in `result.yaml`. When `False`, actually creates/updates the monitor and returns `result.monitor_uuid` + a deep link in `result.instructions`. See `data-monitor-creation.md`. |

---

## Pre-Step: Verify Warehouse

Before creating a table monitor, resolve the warehouse name or UUID. The `warehouse` parameter is required and must match an existing warehouse in the Monte Carlo account.

1. If the user provides a table name, call `get_asset` to retrieve the table details -- the response includes the warehouse name and UUID.
2. If the user provides a database or schema name without a specific table, call `search` with the database or schema name to find assets and identify the warehouse.
3. Use either the warehouse name or UUID in the `warehouse` parameter.

**NEVER guess the warehouse value.** If you cannot resolve it, ask the user.

---

## Asset Selection

The `asset_selection` object defines which tables the monitor covers. It must include a `databases` list.

**Use database and schema scoping to select which tables to monitor.** This is the reliable approach and covers most use cases.

> **Known limitation:** The MCP tool supports `filters` and `exclusions` parameters, but the tool's schema describes the wrong format for them. Until this is fixed ([K2-269](https://linear.app/montecarlodata/issue/K2-269)), **do not pass `filters` or `exclusions`** — they will cause errors. Use database/schema scoping instead to narrow the set of monitored tables. If the user needs regex or pattern-based filtering, explain this limitation and suggest either (a) using schema-level scoping to get close, or (b) creating individual metric monitors for specific tables.

### Database-Level Selection

To monitor all tables in an entire database, specify only the database name with no `schemas` list:

```json
{
  "databases": [
    {"name": "analytics"}
  ]
}
```

This monitors every table in every schema within the `analytics` database.

### Schema-Level Selection

To monitor all tables in specific schemas, include the `schemas` list:

```json
{
  "databases": [
    {
      "name": "analytics",
      "schemas": ["core", "staging"]
    }
  ]
}
```

This monitors every table in the `core` and `staging` schemas within `analytics`, but not tables in other schemas.

### Multiple Databases

You can monitor tables across multiple databases in a single monitor:

```json
{
  "databases": [
    {"name": "analytics", "schemas": ["core"]},
    {"name": "raw_data"},
    {"name": "reporting", "schemas": ["public", "internal"]}
  ]
}
```

---

## Alert Conditions

Alert conditions define which metrics the table monitor tracks. The operator is always AUTO (anomaly detection) -- custom thresholds are not available for table monitors.

| Metric | Description |
|--------|-------------|
| `last_updated_on` | Freshness monitoring. Alerts when a table has not been updated within its normal cadence. |
| `schema` | Any schema change. Alerts when columns are added, removed, or their types change. |
| `schema_fields_added` | New columns detected. Alerts only when new columns appear in the table. |
| `schema_fields_removed` | Columns removed. Alerts only when existing columns are dropped from the table. |
| `schema_fields_type_change` | Column type changes. Alerts only when a column's data type changes. |
| `total_row_count` | Row count changes. Alerts on anomalous changes in total row count. |
| `total_row_count_last_changed_on` | Time since last volume change. Alerts when the row count has not changed for an unusual duration. |

### Notes

- **All operators are AUTO (anomaly detection).** Table monitors do not support custom thresholds like GT, LT, or explicit operators. If the user needs custom thresholds, use a metric monitor instead.
- **No `schedule` field.** Table monitors do not support the `schedule` field in MaC YAML. Adding it will cause a validation error on `montecarlo monitors apply`. Table monitor scheduling is managed automatically by Monte Carlo. Do NOT add a schedule block to the generated YAML.
- The default set (`last_updated_on`, `schema`, `total_row_count`, `total_row_count_last_changed_on`) provides broad coverage and is appropriate for most use cases. Only override the defaults when the user specifically requests a subset.
- `schema` is a superset of `schema_fields_added`, `schema_fields_removed`, and `schema_fields_type_change`. If using `schema`, there is no need to also include the granular schema metrics.

---

## Examples

### Monitor all tables in a database (minimal config)

```json
{
  "name": "analytics_db_monitor",
  "description": "Monitor all tables in the analytics database for freshness, schema changes, and volume",
  "warehouse": "production_warehouse",
  "asset_selection": {
    "databases": [
      {"name": "analytics"}
    ]
  }
}
```

Uses the default alert conditions (`last_updated_on`, `schema`, `total_row_count`, `total_row_count_last_changed_on`).

### Monitor specific schemas with default alerts

```json
{
  "name": "core_schemas_monitor",
  "description": "Monitor all tables in core and reporting schemas",
  "warehouse": "production_warehouse",
  "asset_selection": {
    "databases": [
      {
        "name": "analytics",
        "schemas": ["core", "reporting"]
      }
    ]
  }
}
```

Monitors every table in the `core` and `reporting` schemas, leaving other schemas unmonitored.

### Monitor multiple schemas across databases

```json
{
  "name": "prod_tables_monitor",
  "description": "Monitor production tables across analytics and raw_data databases",
  "warehouse": "production_warehouse",
  "asset_selection": {
    "databases": [
      {
        "name": "analytics",
        "schemas": ["core", "reporting"]
      },
      {
        "name": "raw_data",
        "schemas": ["ingestion"]
      }
    ]
  }
}
```

Monitors tables in specific production schemas, leaving development and staging schemas unmonitored.

### Schema change monitoring only

```json
{
  "name": "warehouse_schema_watch",
  "description": "Track schema changes across the entire data warehouse",
  "warehouse": "production_warehouse",
  "asset_selection": {
    "databases": [
      {"name": "analytics"},
      {"name": "raw_data"}
    ]
  },
  "alert_conditions": [
    "schema_fields_added",
    "schema_fields_removed",
    "schema_fields_type_change"
  ]
}
```

Monitors only schema changes (not freshness or volume) across multiple databases. Uses the granular schema metrics instead of `schema` to allow selectively enabling/disabling each type.

---

## Table Monitor vs Metric Monitor

| Aspect | Table Monitor | Metric Monitor |
|--------|---------------|----------------|
| **Scope** | Multiple tables (database/schema level) | Single table |
| **Metrics** | Freshness, schema changes, row count | Field-level metrics (null rate, mean, sum, etc.) |
| **Operator** | AUTO only (anomaly detection) | AUTO or explicit thresholds (GT, LT, EQ, etc.) |
| **Asset selection** | Database/schema with filters and exclusions | Single table specified by MCON or name |
| **Timestamp field** | Not required | Required (`aggregate_time_field`) |
| **Segmentation** | Not available | Available via `segment_fields` |
| **Best for** | Broad coverage, freshness, schema drift | Targeted field-level data quality checks |

**Rule of thumb:** If the user wants to monitor a specific field on a specific table with specific thresholds, use a metric monitor. If the user wants broad monitoring across many tables with automatic anomaly detection, use a table monitor.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 323kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 323kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 323kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall