Skip to main content
Glama
Sign In
dataranger

dataranger

by akshaysharma1088
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

patrol_snowflake

Check date-partitioned Snowflake fact tables for quality incidents, test proposed fixes against control totals, and classify each as auto-fixed, no action, or escalate.

Instructions

Check a fact table in Snowflake for data-quality incidents and say which are safe to fix.

A patrol checks every daily partition of the fact table for duplicate keys, duplicate rows, missing
partitions, rows that point to no reference record, null spikes, and row counts or amounts that do not
match the source's control totals. For each problem it proposes a fix, tests that fix on a copy against
the control totals, and decides: "auto-fixed" (proven and low risk), "no action needed" (checked, the
data is right) or "escalate" (a person must decide).

Use this before trusting, querying or building on a date-partitioned Snowflake table, or after a load to
confirm the data is still right. Use patrol_dbt instead when the table is built by a dbt model,
patrol_duckdb for a DuckDB file and patrol_files for CSV or Parquet exports. Use run_demo to see the
output on sample data.

Behavior: connects to Snowflake with credentials already configured on this machine; none are passed
as arguments. It runs three SELECT statements and nothing else, so the warehouse is never modified,
and it selects only the mapped columns for the last `days` days, so it uses a little warehouse compute
(usually seconds for 30 days). The only side effect is writing four report files to out_dir:
dashboard.html, audit.jsonl, incidents.csv and fixed_version.csv (the proposed corrected table, for
review). Fails with a readable error if the login is refused, or a table or mapped column does not exist.

Returns the counts (incidents, auto_fixed, no_action_needed, escalate), needs_a_person (the escalated
incidents), all_incidents (partition, problems, decision, proposed_fix, residual for each) and
outputs (paths to the report files). Pass outputs.folder and a partition to get_incident for the
full evidence behind one decision. Tell the user about every escalated incident.

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": {
      "table": "<table>",
      "ref_table": "<ref_table>",
      "manifest_table": "<manifest_table>"
    },
    "name": "patrol_snowflake"
  }
}

Input Schema

NameRequiredDescriptionDefault
keyNoColumn in the fact table that uniquely identifies a row (the primary key).txn_id
dateNoDate column the fact table is partitioned by, one partition per calendar day. The control totals must have a column with the same name.txn_date
daysNoRead only the last N days of the fact table and control totals (today counts as day one). Use at least 30 so the checks have a baseline. Pass null to read the whole table, which can be slow and costly.
tableYesFact table to check, for example ANALYTICS.GOLD.PAYMENTS. An unqualified name uses the connection's database and schema.
amountNoNumeric amount column in the fact table. It is compared with the 'amount' control total.amount
out_dirNoFolder to write the report files into. Created if missing; report files already there are overwritten. Omit to use a new temporary folder; its path comes back in outputs.folder.
ref_keyNoColumn in the reference table that the fact table's reference column must match.customer_id
segmentNoColumn that splits each day into segments, for example channel or region. The control totals must have a column with the same name, where '*' means the whole day.channel
categoryNoOptional categorical column in the fact table. Omit if the table has none.
ref_tableYesReference table that fact rows point to, for example ANALYTICS.GOLD.CUSTOMERS.
referenceNoColumn in the fact table that points to the reference table (the foreign key).customer_id
thresholdNoGate threshold: the largest relative gap to the control totals that a verified fix may leave and still be marked auto-fixed (0.01 = 1%). Lower is stricter. Omit for the benchmark-calibrated default, 0.0135.
connectionNoName of a connection in ~/.snowflake/connections.toml. Omit to use the server's SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER, SNOWFLAKE_PASSWORD or SNOWFLAKE_PRIVATE_KEY_PATH, SNOWFLAKE_ROLE and SNOWFLAKE_WAREHOUSE environment variables, or the Snowflake connector's default connection.
manifest_tableYesTable of the source system's control totals, one row per date and segment, with columns: the date column, the segment column ('*' = whole day), n (row count) and amount (sum).

Output Schema

NameRequiredDescriptionDefault
noteYes
tableYes
outputsYes
escalateYes
incidentsYes
auto_fixedYes
rows_checkedYes
all_incidentsYes
gate_thresholdYes
needs_a_personYes
no_action_neededYes

Schema Changelog

Changes observed during successful MCP inspections.

  1. Addedv0.5.1

TDQS

A4.6/5.0
Behavior5/5

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

Beyond the annotations, the description discloses authentication behavior, that only three SELECT statements run, that the warehouse is never modified, expected compute cost, and the four report files written to out_dir. It also explains failure modes and that escalated incidents must be reported to the user. This is rich behavioral context that the annotations alone do not provide.

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?

The description is long but well structured and front-loaded: purpose, checks, decision categories, usage, alternatives, behavior, and returns. Most sentences earn their place, though the return-value paragraph partially duplicates the output schema. It is slightly verbose but not wasteful.

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?

Given a 14-parameter tool with a rich output schema, the description covers purpose, usage, side effects, failure modes, and escalation handling. The output schema handles return structure, but the description still gives enough operational context for an agent to call and interpret the tool correctly.

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

Parameters3/5

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

Schema description coverage is 100%, so the input schema already documents all 14 parameters thoroughly. The description adds useful cross-parameter context about mapped columns, the days window, configured credentials, and report outputs, but it does not add much per-parameter meaning beyond the schema. A baseline score of 3 is appropriate.

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?

The description states a specific verb and resource: checking a Snowflake fact table for data-quality incidents and identifying which fixes are safe. It clearly distinguishes the tool from patrol_dbt, patrol_duckdb, and patrol_files, and explains the patrol outcome categories. An agent can identify what this tool does without opening the schema.

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

Usage Guidelines5/5

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

It explicitly says to use this before trusting, querying, or building on a date-partitioned Snowflake table, and after a load to confirm correctness. It names alternatives for dbt, DuckDB, CSV/Parquet, and demo scenarios, giving clear when-to-use and when-not-to-use guidance.

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

Deploy Server

Other Tools