MCPg - Production-grade PostgreSQL MCP Server

Overview Schema Source Related Servers Discussions Admin

Detect vector outliers

detect_vector_outliers

Read-only

Detect pgvector embedding outliers in a table by k-means clustering sampled rows and flagging vectors with within-cluster distance z-scores above a threshold, revealing rows anomalous for their group.

Instructions

Flag pgvector rows whose embedding sits far from any cluster centroid. Samples up to sample_size (default 5000) non-NULL rows of schema.table.embedding_column, clusters them with k-means (same engine as cluster_vectors), then per cluster computes a z-score on the distance from each row to its centroid and flags rows whose z-score exceeds zscore_threshold (default 3.0). Per-cluster scoring catches rows that are weird-for-their-group rather than weird-overall, which is usually what 'find outliers' should mean. Returns outliers sorted by z-score descending (capped at max_results), total_outliers (the unclipped count), and cluster_stats (per-cluster mean / std of within-cluster distances). When id_column is set each outlier carries that column's value; otherwise the row's positional sample index. k >= 2 and there must be at least 2k parseable rows. Reports available=false if pgvector is not installed.

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>"
    },
    "name": "detect_vector_outliers"
  }
}

Input Schema

Name	Required	Description	Default
`k`	No
`seed`	No
`table`	Yes
`metric`	No		l2
`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.
`id_column`	No
`max_results`	No
`sample_size`	No
`max_iterations`	No
`embedding_column`	Yes
`zscore_threshold`	No

Output Schema

Name	Required	Description	Default
`k`	Yes
`metric`	Yes
`outliers`	Yes
`available`	Yes
`dimension`	Yes
`sampled_rows`	Yes
`cluster_stats`	Yes
`total_outliers`	Yes
`zscore_threshold`	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.4/5.0

Behavior4/5

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

Annotations only cover read-only and closed-world safety, and the description goes well beyond them: it discloses the sampling strategy (up to sample_size non-NULL rows, default 5000), the hard preconditions (k >= 2, at least 2k parseable rows), and the availability failure mode (available=false when pgvector is absent). It does not mention cost/latency implications of sampling and clustering a large table, which keeps it from a 5.

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?

A single dense paragraph with the core action front-loaded and no filler sentences; the sampling, threshold, and return-value details each add information. It would read faster with light structure given its length, and the return-value sentence is partly redundant with the existing output schema.

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 a 12-parameter analytical tool with an output schema, the description covers what an agent needs: what is sampled, how scoring works, preconditions, failure modes, and result shape. The remaining undocumented knobs (metric, seed, max_iterations) are tuning parameters with sensible defaults rather than blockers to a correct first call.

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 8%, so the description carries most of the burden and largely does: it defines sample_size, zscore_threshold, id_column, max_results, and k, including defaults and the k >= 2 constraint. It leaves metric, seed, and max_iterations entirely unexplained in both schema and description, which is a real gap for a 12-parameter tool.

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: 'Flag pgvector rows whose embedding sits far from any cluster centroid.' The method (k-means per cluster, then z-score of centroid distance) is spelled out, so the agent can distinguish this from sibling clustering/drift tools like cluster_vectors or monitor_embedding_drift without opening any schema.

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?

It states the intended semantics of the operation, noting that per-cluster scoring 'is usually what find outliers should mean' versus weird-overall detection, which gives real context for choosing it. It also points at cluster_vectors as the shared engine. It stops short of explicit when-not conditions or naming alternative tools for adjacent tasks (drift monitoring, recall analysis), so it falls shy of a 5.

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

Deploy Server