Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/A-Point-Systems-ltd/ms-sql-mcp/llms.txt

Use this file to discover all available pages before exploring further.

UpsertInsight creates or updates an insight row for a database object in AIInsights.SchemaInsights. It is the primary mechanism for agents to upgrade auto-mechanical baselines with real LLM-authored summaries. The implementation runs UPDATE first and falls back to INSERT only when no matching row exists. The schema fingerprint and object_id of the live object are captured automatically server-side at write time — callers do not provide these values.

​
Parameters

​
objectType
string
required
Object type label to store in AIInsights.SchemaInsights. Must be one of: Table, View, Procedure, Function, Trigger.
​
schemaName
string
Schema name of the object. Pass dbo for the default schema. Pass null only when the schema is genuinely unknown.
​
objectName
string
required
Object name without schema prefix (e.g. TableProblems).
​
description
string
required
Short single-sentence description of what this object is.
​
businessPurpose
string
Why this object exists from a business or operational perspective. Pass null to skip.
​
dataPatterns
string
Data patterns: typical volume, key columns, hot filters, and partitioning hints. Pass null to skip.
​
usageGuidelines
string
Usage guidance for analysts and agents: preferred joins, filters, and gotchas. Pass null to skip.
​
relatedObjects
string
Related objects as a JSON array string, e.g. '["Buildings","Suppliers"]'. Pass null to skip.
​
llmModel
string
Identifier of the LLM or process that produced the insight (e.g. gpt-4o, claude-3-5-sonnet, manual-validation). Stored for provenance. Defaults to unknown.
​
confidence
decimal
Confidence score between 0 and 1. Use 0.8 as a sensible default for a properly authored insight. Defaults to 0.8.
​
analyzedBy
string
Name or identifier of the agent, analyst, or process that authored the insight (e.g. investigation-agent, JIRA-1234). Defaults to MCP.
​
columnName
string
Column name when authoring a column-level insight. Pass null (or omit) for table- or object-level insights.

​
Fingerprint

The schema fingerprint is computed server-side at write time from live sys.* metadata. You do not need to supply or calculate it. The fingerprint is used by subsequent GetInsight calls to detect whether the object has been altered since the insight was written.

​
Returns

​
success
boolean
required
true when the row was written successfully; false on error.
​
data
object
Present when success is true. Contains a confirmation message and the insight ID of the written row.
​
error
string
Present only when success is false. Contains the exception message.
UpsertInsight requires USE_INSIGHTS_LAYER to be enabled (the default) and the AI Insights layer to be installed via InstallInsightsLayer. When the layer is disabled, the tool returns an error without writing to the database.
Never pass llmModel="auto-mechanical" or confidence <= 0.30 when calling UpsertInsight directly. Those values are reserved for machine-generated placeholder baselines and signal to downstream tools that the insight still needs upgrading. A properly authored insight should have a real model identifier and a confidence of 0.7 or higher.
When a DescribeTable, DescribeView, or GetObject response includes insightEnrichment.required=true, the insightEnrichment.nextAction.args object already contains a pre-filled UpsertInsight argument template. Use it as your starting point and replace the <fill in: ...> placeholder values with your analysis results.

Build docs developers (and LLMs) love

Get started for freeTalk to us