MCPg - Production-grade PostgreSQL MCP Server

Overview Schema Source Related Servers Discussions Admin

Monitor embedding drift

monitor_embedding_drift

Read-only

Detect distributional drift between two time windows of a pgvector embedding column by comparing centroid cosine distance and L2-norm changes, flagging pipeline or model swaps.

Instructions

Compare two time windows of a pgvector column and flag distributional drift. Samples up to sample_size (default 5000) non-NULL embeddings from each window (filtered by timestamp_column), computes the centroid (per-dimension mean vector) and L2-norm distribution of each, then reports the cosine distance between the two centroids (the main drift signal), the relative change in mean / std of the L2-norm distribution, and a boolean drift_detected that flips when cosine distance exceeds drift_threshold (default 0.05). Each window is treated as a half-open [start, end) interval. Useful for ops monitoring of embedding pipelines — an upstream model swap typically shows up as a large centroid cosine distance even if the norm distribution looks stable. insufficient_data is returned distinctly from drift_detected=false when either window is empty. Reports available=false if pgvector is not installed.

Example: monitor_embedding_drift(schema='public', table='docs', embedding_column='embedding', timestamp_column='created_at', baseline_start='2026-01-01', baseline_end='2026-02-01', current_start='2026-02-01', current_end='2026-03-01')

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "schema": "<schema>",
      "table": "<table>",
      "embedding_column": "<embedding_column>",
      "timestamp_column": "<timestamp_column>",
      "baseline_start": "<baseline_start>",
      "baseline_end": "<baseline_end>",
      "current_start": "<current_start>",
      "current_end": "<current_end>"
    },
    "name": "monitor_embedding_drift"
  }
}

Input Schema

Name	Required	Description
`table`	Yes
`schema`	Yes
`database`	No	Optional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected.
`current_end`	Yes
`sample_size`	No
`baseline_end`	Yes
`current_start`	Yes
`baseline_start`	Yes
`drift_threshold`	No
`embedding_column`	Yes
`timestamp_column`	Yes

Output Schema

Name	Required	Description	Default
`notes`	Yes
`current`	Yes
`baseline`	Yes
`available`	Yes
`dimension`	Yes
`drift_detected`	Yes
`drift_threshold`	Yes
`insufficient_data`	Yes
`centroid_cosine_distance`	Yes
`norm_std_relative_change`	Yes
`norm_mean_relative_change`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv0.8.4Nov 5, 2026

changedInput schema / properties / database / description

Previous value: -"Optional: target a configured secondary (read-only) database by name; omit for the primary. Call list_databases to see the configured ids."New value: +"Optional: a database id from list_databases, to target a configured secondary (read-only) database; omit for the primary. Database names that are not configured ids are rejected."

First observedv0.6.8Jul 6, 2026

TDQS

A4.6/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Goes well beyond the readOnly/openWorld annotations: it discloses sampling behavior (up to sample_size non-NULL embeddings), how windows are bounded (half-open [start, end)), what signal is primary, the exact condition that flips drift_detected, and two distinct failure modes (insufficient_data for empty windows, available=false without pgvector). This is the kind of operational detail an agent cannot infer from the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core action and signal, then adds mechanism, edge cases, and a concrete call example. Dense but every sentence carries information; the only minor cost is a long single paragraph that could be split for scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, 8-required analytical tool, the description covers inputs, computation, primary and secondary metrics, thresholds, and degraded-mode returns. An output schema exists, yet the description still names the key result fields, so an agent knows how to interpret the response without opening it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 9%, so the description must carry the load, and it does for most parameters: sample_size (default 5000, sampling cap), drift_threshold (default 0.05, the flip condition), timestamp_column (the filter field), embedding_column, and the four window boundaries via the half-open interval rule plus a worked example. The `database` parameter is documented in the schema itself rather than the description, leaving only a minor gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: 'Compare two time windows of a pgvector column and flag distributional drift.' The scope (two windows, centroid cosine distance, L2-norm distribution) clearly separates it from neighboring vector tools such as detect_vector_outliers, analyze_topk_stability, or cluster_vectors.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a concrete usage context — ops monitoring of embedding pipelines, where an upstream model swap surfaces as a large centroid cosine distance. It never names an alternative tool or states when NOT to use this one (e.g., versus drift checks on other column types), so it stops short of explicit routing guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server