mcp-usage

MCP Usage Rules

Incident MCP

• Incident ID required: If not provided or unclear, ask the user for the incident ID before making the MCP call. Incident ID is numeric; if user says "INC-1234", use 1234.
• Start with GetIncidentById for general incident information (status, severity, affected datasources, events summary, timestamps).
• Use GetEventDetails for deeper investigation: specific event, contract field data (before/after), historical chart data, detailed event metadata. Use when user asks about specific metrics, fields, or data quality, or when you need to explain what changed.
• Event count strategy: 1-2 events → fetch GetEventDetails for all; 10+ events → use GetEventDetails only for most relevant events or skip if general data is sufficient.
• Warehouse queries for incidents: Always apply pivot filters from the event in every warehouse query (field_name, value, field_type — use field_type for correct SQL: strings in quotes, numerics without). Use timestamp_column and timestamp for time-based filtering; see docs/reference.md for SQL examples.

Warehouse Query MCP

• Always add LIMIT: Every query must include a LIMIT clause (default LIMIT 10 unless user requests more). Inform the user when you limit results.
• Show the SQL query to the user when you wrote it, before or alongside results.
• Display results with original column names — do not rename, combine, or transform column names.
• Format results as tables preserving column structure.
• Best practices: start with LIMIT 10 to verify query and understand structure; use table schema and partition info from upriver-context; filter on partition columns when possible. For error handling and known root causes, see docs/reference.md.

Profile Diff MCP

• When to use: Compare data profiles between two tables, views, or external tables (e.g. production vs staging); understand differences in distributions, completeness, cardinality; investigate data migration or transformation issues. Treat views and external tables like regular tables.
• Use WHERE clauses for large tables: Find partition/cluster columns from upriver-context (Databricks/Athena: partition_index; Snowflake: clustering_key; Redshift: sortkey/distkey). Prefer time-based partitions; use same time range for both sides (e.g. first_where_clause='event_date = "2024-01-15"', second_where_clause='event_date = "2024-01-15"').
• Workflow: Check upriver-context for table metadata and partition/cluster columns → identify time ranges or filters → run profile diff with WHERE clauses on same data subset → analyze differences and related code → present findings. See docs/reference.md for full workflow and partition strategy examples.
• If uncertain about filtering, limiting, or partitions, ask the user for clarification or help.