DbOperationResult: the standard tool response shape

Every one of the 19 MSSQL MCP Server tools returns a DbOperationResult object. The shape is consistent across read, write, and AI Insights operations, with tool-specific payload carried in the data field. This predictable envelope makes it straightforward for MCP clients and LLM agents to detect failures, count affected rows, and extract structured results without tool-specific parsing logic.

Core fields

success

boolean

required

Whether the operation completed without error. A true value means the SQL was executed and the result was serialized successfully. A false value means something went wrong — check error for the message.

error

string | null

Human-readable error message when success is false. Set to null on success. Errors include connection failures, SQL classification rejections (e.g. passing a SELECT to ExecuteSQL), permission errors, and runtime exceptions.

rowsAffected

integer | null

Populated by DML tools: InsertData, UpdateData, and ExecuteSQL. Reflects the integer returned by the underlying ADO.NET ExecuteNonQuery call. null for read-only tools and insight query tools that do not modify rows.

data

object | array | null

Tool-specific payload. The shape varies by tool:

Read tools (ReadData, ListObjects) — an array of row objects.
Introspection tools (DescribeTable, DescribeView, GetObject) — a metadata object; when the AI Insights layer is enabled, additional top-level keys are merged in (see Insight metadata fields below).
DML tools (InsertData, UpdateData, ExecuteSQL) — typically null or a minimal confirmation object; row count is in rowsAffected.
Insight tools (GetInsight, InsightsCheck, etc.) — a structured object specific to each insight operation.

Example responses

Successful read — `ReadData` / `ListObjects`

{
  "success": true,
  "error": null,
  "rowsAffected": null,
  "data": [
    { "TABLE_SCHEMA": "dbo", "TABLE_NAME": "Orders", "TABLE_TYPE": "BASE TABLE" },
    { "TABLE_SCHEMA": "dbo", "TABLE_NAME": "Customers", "TABLE_TYPE": "BASE TABLE" }
  ]
}

Successful DML — `InsertData`

{
  "success": true,
  "error": null,
  "rowsAffected": 1,
  "data": null
}

Error response

{
  "success": false,
  "error": "ExecuteSQL does not allow SELECT or other read-only queries. Use ReadData for all SELECT statements, including sys.*, INFORMATION_SCHEMA, and DMVs.",
  "rowsAffected": null,
  "data": null
}

Insight metadata fields

When the AI Insights layer is enabled (USE_INSIGHTS_LAYER is not set to a falsey value), the introspection tools DescribeTable, DescribeView, and GetObject merge the following top-level keys into their data payload. This is a best-effort enrichment — a failure to read insight metadata never causes the parent tool call to fail.

insight

object | null

The cached SchemaInsight row projected for API response. null when no cached insight exists for the object and auto-population did not produce one. See SchemaInsight fields below for the full field list.

insightFreshness

string

Freshness classification of the cached insight. One of:

Value	Meaning
`Fresh`	Cached insight matches the live object definition (fingerprint + `modify_date`).
`Absent`	No row in `AIInsights.SchemaInsights`; a baseline may be created on the next introspection if auto-population is enabled.
`StaleArchived`	Cached row was archived to `InsightHistory` due to DDL change or fingerprint drift.
`LayerDisabled`	`USE_INSIGHTS_LAYER=false`; insight enrichment was skipped.
`AccessDenied`	Could not read the live object definition due to insufficient permissions.
`DefinitionUnavailable`	Object exists but its definition could not be resolved.

enrichmentSuggested

boolean

true when the cached insight is an auto-mechanical baseline (LlmModel = "auto-mechanical", Confidence = 0.30). Signals to MCP-aware agents that the insight should be upgraded via UpsertInsight before answering the user.

insightEnrichment

object | null

Full enrichment directive, present only when enrichmentSuggested is true and INSIGHTS_AUTOPOPULATE is enabled. Includes a pre-filled UpsertInsight argument template (with <fill in: …> placeholders), a list of related objects to introspect, enrichment instructions, and completion criteria. Conforms to protocol MCP-Insight-Enrichment-v1.

_agentDirective

string | null

Mandatory instruction text injected when enrichment is required. Present only when enrichmentSuggested is true. Instructs the agent to call UpsertInsight for the current object (and any relatedObjectsToIntrospect) before producing a final answer to the user. Skipping this call is flagged as a protocol violation.

pendingEnrichments

array | null

List of objects requiring UpsertInsight calls, each entry containing tool, target, objectType, and reason. Present alongside _agentDirective when enrichment is required.

SchemaInsight fields

Show insight object fields

insightId

integer

Auto-increment primary key of the AIInsights.SchemaInsights row.

objectType

string

Database object type, e.g. Table, View, StoredProcedure, Function, Trigger.

schemaName

string

SQL schema of the object, e.g. dbo.

objectName

string

Unqualified name of the object.

columnName

string | null

Column name for column-level insights; null for object-level insights.

description

string | null

Short human-readable description of the object or column.

businessPurpose

string | null

Explanation of why the object exists from a business domain perspective.

dataPatterns

string | null

Notes on data volume, key columns, hot filter columns, and value distributions.

usageGuidelines

string | null

Preferred join patterns, filter strategies, known gotchas, and indexing notes.

JSON array of qualified object names (schema.name) that are related to this object.

llmModel

string | null

Identifier of the model that authored the insight. "auto-mechanical" indicates a server-generated baseline that has not yet been enriched by an LLM agent.

confidence

decimal | null

Authoring confidence score. Auto-mechanical baselines use 0.30; LLM-authored insights should be > 0.30 (conventionally 0.85).

lastAnalyzed

string (ISO 8601) | null

UTC timestamp of when the insight was last written or updated.

analyzedBy

string | null

Agent or process name that authored the insight.

version

integer | null

Monotonically increasing version counter, incremented on each UpsertInsight call.

modifyDateAtAnalysis

string (ISO 8601) | null

The modify_date of the object in sys.objects at the time the insight was written. Used for staleness detection.

schemaFingerprint

string | null

Hash of the object’s structural definition at analysis time. Compared against the live fingerprint on read to detect DDL drift.

enrichmentSuggested

boolean

Convenience projection: true when llmModel equals "auto-mechanical". Mirrors the top-level enrichmentSuggested field for consumers that only inspect the insight sub-object.

Overview

Inspection Tools

Write & DDL Tools

Insights Tools

DbOperationResult: the standard tool response shape

Core fields

Example responses

Successful read — `ReadData` / `ListObjects`

Successful DML — `InsertData`

Error response

Insight metadata fields

SchemaInsight fields

Build docs developers (and LLMs) love

Overview

Inspection Tools

Write & DDL Tools

Insights Tools

Documentation Index

​Core fields

​Example responses

​Successful read — ReadData / ListObjects

​Successful DML — InsertData

​Error response

​Insight metadata fields

​SchemaInsight fields

Build docs developers (and LLMs) love

Core fields

Example responses

Successful read — `ReadData` / `ListObjects`

Successful DML — `InsertData`

Error response

Insight metadata fields

SchemaInsight fields