SQL MCP Server エンティティに説明を追加する

説明は、AI エージェントが SQL MCP Server データベース スキーマを理解するのに役立つセマンティック メタデータです。 エンティティ、フィールド、パラメーターに説明を追加すると、言語モデルによって、クエリを実行するデータとその使用方法についてより適切な決定が行われます。 この記事では、Data API Builder CLI を使用してすべてのレベルで説明を追加し、AI エージェントの精度とツール検出を向上させる方法について説明します。

説明を追加する理由

AI エージェントは、コンテキストに依存してデータを理解します。 説明がない場合、エージェントには ProductID や dbo.Ordersなどの技術名のみが表示されます。 説明により、エージェントは、 ProductID が "カタログ内の各製品の一意識別子" であり、 dbo.Orders には "品目と出荷の詳細を含む顧客の発注書" が含まれていることを理解します。

説明の改善:

• ツール検出 - エージェントが適切なエンティティをより迅速に見つける
• クエリの精度 - エージェントは適切なコンテキストを使用してより優れたクエリを作成します
• パラメーターの使用法 - エージェントがストアド プロシージャに正しい値を指定する
• フィールドの選択 - エージェントは関連するフィールドのみを返します

エンティティの説明

エンティティの説明では、テーブル、ビュー、またはストアド プロシージャが表す内容を説明します。 エンティティを作成または更新するときに追加します。

説明をdab addで追加する

新しいエンティティを追加するときは、 --description フラグを使用します。

dab add Products \
  --source dbo.Products \
  --permissions "anonymous:*" \
  --description "Product catalog with pricing, inventory, and supplier information"

説明をdab updateで追加する

既存のエンティティの説明を追加または変更できます。

dab update Products \
  --description "Product catalog with pricing, inventory, and supplier information"

例示

テーブルの説明:

dab add Orders \
  --source dbo.Orders \
  --permissions "authenticated:read" \
  --description "Customer purchase orders with line items, shipping details, and payment status"

説明を表示する:

dab add ActiveProducts \
  --source dbo.vw_ActiveProducts \
  --source.type view \
  --source.key-fields "ProductID" \
  --permissions "anonymous:read" \
  --description "Currently available products with positive inventory and active status"

ストアド プロシージャの説明:

dab add GetOrderHistory \
  --source dbo.usp_GetOrderHistory \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --description "Retrieves complete order history for a customer including items, totals, and shipping tracking"

フィールドの説明

フィールドの説明では、各列が何を表しているのかを説明します。 彼らはエージェントが個々のデータポイントの目的と意味を理解するのを助けます。

を使用してフィールドの説明を追加する dab update

--fields.nameフラグと--fields.description フラグを一緒に使用します。

dab update Products \
  --fields.name ProductID \
  --fields.description "Unique identifier for each product" \
  --fields.primary-key true

複数のフィールドの説明を追加する

複数のフィールドに説明を追加するには、 dab update を複数回呼び出します。

dab update Products \
  --fields.name ProductID \
  --fields.description "Unique identifier for each product" \
  --fields.primary-key true

dab update Products \
  --fields.name ProductName \
  --fields.description "Display name of the product"

dab update Products \
  --fields.name UnitPrice \
  --fields.description "Retail price per unit in USD"

dab update Products \
  --fields.name UnitsInStock \
  --fields.description "Current inventory count available for purchase"

dab update Products \
  --fields.name Discontinued \
  --fields.description "True if product is no longer available for sale"

フィールド説明の最適な方法

次のような明確で簡潔な説明を使用します。

• 目的 - フィールドが表す内容
• 単位 - 通貨、測定値、タイム ゾーン
• 書式 - 日付形式、文字列パターン
• ビジネス ルール - 有効な範囲、制約

良い例:

# Include units
dab update Products \
  --fields.name Weight \
  --fields.description "Product weight in kilograms"

# Include format details
dab update Orders \
  --fields.name OrderDate \
  --fields.description "Order placement date in UTC (ISO 8601 format)"

# Include business context
dab update Employees \
  --fields.name HireDate \
  --fields.description "Date employee was hired, used for calculating benefits eligibility"

# Include constraints
dab update Products \
  --fields.name ReorderLevel \
  --fields.description "Minimum stock level that triggers automatic reorder (must be positive integer)"

パラメーターの説明

パラメーターの説明は、ストアド プロシージャの実行時に指定する値をエージェントが理解するのに役立ちます。 この方法は、ストアド プロシージャを呼び出す MCP ツールにとって特に重要です。

パラメーターの説明を追加する dab add

ストアド プロシージャを追加する場合は、パラメーター メタデータにコンマ区切りのリストを使用します。

dab add GetOrdersByDateRange \
  --source dbo.usp_GetOrdersByDateRange \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --description "Retrieves all orders placed within a specified date range" \
  --parameters.name "StartDate,EndDate,CustomerID" \
  --parameters.description "Beginning of date range (inclusive),End of date range (inclusive),Optional customer ID filter (null returns all customers)" \
  --parameters.required "true,true,false" \
  --parameters.default ",,null"

パラメーターの説明を追加する dab update

既存のストアド プロシージャのパラメーターの説明を更新できます。

dab update GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate,CustomerID" \
  --parameters.description "Beginning of date range (inclusive),End of date range (inclusive),Optional customer ID filter (null returns all customers)" \
  --parameters.required "true,true,false"

パラメーターの説明の形式

パラメーターでは、コンマ区切りのリストが使用されます。ここで、

• --parameters.name - パラメーター名の順序
• --parameters.description - 対応する説明
• --parameters.required - 各パラメーターが必要かどうか (true/false)
• --parameters.default - 既定値 (必須パラメーターの場合は空の文字列)

パラメーターの詳細な説明を含む例:

dab add SearchProducts \
  --source dbo.usp_SearchProducts \
  --source.type stored-procedure \
  --permissions "anonymous:execute" \
  --description "Searches products by keyword, category, and price range" \
  --parameters.name "SearchTerm,CategoryID,MinPrice,MaxPrice,PageSize,PageNumber" \
  --parameters.description "Keyword to search in product names and descriptions,Product category ID (null searches all categories),Minimum price filter in USD (null removes lower bound),Maximum price filter in USD (null removes upper bound),Number of results per page (default 20, max 100),Page number for pagination (1-based)" \
  --parameters.required "true,false,false,false,false,false" \
  --parameters.default ",null,null,null,20,1"

完全なワークフロー例

すべてのレベルで説明を追加する方法を示す完全な例を次に示します。

1. 説明を含むエンティティを作成する

dab add Customers \
  --source dbo.Customers \
  --permissions "authenticated:read,update" \
  --description "Customer master records including contact information, billing preferences, and account status"

2. フィールドの説明を追加する

dab update Customers \
  --fields.name CustomerID \
  --fields.description "Unique customer identifier (auto-generated)" \
  --fields.primary-key true

dab update Customers \
  --fields.name CompanyName \
  --fields.description "Customer company or organization name"

dab update Customers \
  --fields.name ContactEmail \
  --fields.description "Primary contact email address for order notifications"

dab update Customers \
  --fields.name Phone \
  --fields.description "Primary phone number in E.164 format (+1234567890)"

dab update Customers \
  --fields.name AccountBalance \
  --fields.description "Current account balance in USD (negative indicates credit)"

dab update Customers \
  --fields.name PreferredCurrency \
  --fields.description "Customer's preferred billing currency (ISO 4217 code)"

dab update Customers \
  --fields.name IsActive \
  --fields.description "Account status flag (false indicates suspended or closed account)"

dab update Customers \
  --fields.name CreatedDate \
  --fields.description "Account creation timestamp in UTC"

dab update Customers \
  --fields.name LastOrderDate \
  --fields.description "Date of most recent order (null for customers with no orders)"

3. パラメーターの説明を含む関連するストアド プロシージャを追加する

dab add UpdateCustomerPreferences \
  --source dbo.usp_UpdateCustomerPreferences \
  --source.type stored-procedure \
  --permissions "authenticated:execute" \
  --description "Updates customer communication and billing preferences" \
  --parameters.name "CustomerID,EmailNotifications,SMSNotifications,PreferredCurrency,MarketingOptIn" \
  --parameters.description "Customer ID to update,Enable email notifications for orders and promotions,Enable SMS notifications for shipping updates,Preferred billing currency (ISO 4217 code),Opt in to marketing communications" \
  --parameters.required "true,false,false,false,false" \
  --parameters.default ",true,false,USD,false"

構成設定における説明の表示

説明は、 dab-config.json ファイルに格納されます。 表示方法を次に示します。

{
  "entities": {
    "Products": {
      "description": "Product catalog with pricing, inventory, and supplier information",
      "source": {
        "object": "dbo.Products",
        "type": "table"
      },
      "fields": {
        "ProductID": {
          "description": "Unique identifier for each product",
          "isPrimaryKey": true
        },
        "ProductName": {
          "description": "Display name of the product"
        },
        "UnitPrice": {
          "description": "Retail price per unit in USD"
        }
      },
      "permissions": [
        {
          "role": "anonymous",
          "actions": ["*"]
        }
      ]
    },
    "GetOrdersByDateRange": {
      "description": "Retrieves all orders placed within a specified date range",
      "source": {
        "object": "dbo.usp_GetOrdersByDateRange",
        "type": "stored-procedure",
        "parameters": {
          "StartDate": {
            "description": "Beginning of date range (inclusive)",
            "required": true
          },
          "EndDate": {
            "description": "End of date range (inclusive)",
            "required": true
          },
          "CustomerID": {
            "description": "Optional customer ID filter (null returns all customers)",
            "required": false,
            "default": null
          }
        }
      },
      "permissions": [
        {
          "role": "authenticated",
          "actions": ["execute"]
        }
      ]
    }
  }
}

エージェントが説明を使用する方法

AI エージェントは、 describe_entities MCP ツールを呼び出すと、スキーマ情報と共に説明を受け取ります。

{
  "entities": [
    {
      "name": "Products",
      "description": "Product catalog with pricing, inventory, and supplier information",
      "fields": [
        {
          "name": "ProductID",
          "type": "int",
          "description": "Unique identifier for each product",
          "isKey": true
        },
        {
          "name": "UnitPrice",
          "type": "decimal",
          "description": "Retail price per unit in USD"
        }
      ],
      "operations": ["read_records", "create_record", "update_record"]
    }
  ]
}

エージェントは、次の目的でこの情報を使用します。

• 適切なエンティティを選択する - ユーザーの意図とエンティティの説明を一致させる
• 関連するフィールドの選択 - 説明に基づいて必要なフィールドのみを返します
• 正確なクエリを作成 する - リレーションシップと制約を理解する
• 正しいパラメーターを指定 する - ストアド プロシージャに適切な値を提供します

ベスト プラクティス

推奨

• 具体的に 指定する - "顧客の配送先住所" は "住所" よりも優れています
• 単位を含める - "PRICE in USD"、"Weight in kgs"
• 言及された形式 - "ISO 8601 日付形式"、"E.164 電話番号形式"
• ビジネス ルールの説明 - "負の値はクレジット残高を示す"
• 省略可能なフィールドに注意してください - "省略可能。null は、すべての結果を返します"
• 説明を最新の状態に保つ - スキーマが変更されたときに説明を更新する

できません

• 技術的な専門用語のみを使用しない - 技術的 な詳細と共にビジネス コンテキストを追加する
• フィールド名を重複させないでください - 「ProductIDは製品IDです」では価値がありません
• 小説を書かない - 説明を簡潔にする (1 ~ 2 文)
• パラメーターの順序を忘れないでください - コンマ区切りのリストが正しく揃っていることを確認する
• null 許容フィールドを無視しないでください - null値に特別な意味がある場合は言及してください

スクリプト記述の更新

大規模なスキーマの場合は、ループを使用して説明の更新をスクリプト化できます。

#!/bin/bash

# Array of field descriptions for Products table
declare -a fields=(
  "ProductID:Unique identifier for each product:true"
  "ProductName:Display name of the product:false"
  "SupplierID:ID of the supplier providing this product:false"
  "CategoryID:Product category classification:false"
  "QuantityPerUnit:Standard packaging quantity (e.g., '12 bottles per case'):false"
  "UnitPrice:Retail price per unit in USD:false"
  "UnitsInStock:Current inventory count available for purchase:false"
  "UnitsOnOrder:Quantity ordered from supplier but not yet received:false"
  "ReorderLevel:Minimum stock level that triggers automatic reorder:false"
  "Discontinued:True if product is no longer available for sale:false"
)

# Loop through and add descriptions
for field in "${fields[@]}"; do
  IFS=':' read -r name desc is_pk <<< "$field"
  if [ "$is_pk" = "true" ]; then
    dab update Products --fields.name "$name" --fields.description "$desc" --fields.primary-key true
  else
    dab update Products --fields.name "$name" --fields.description "$desc"
  fi
done

関連コンテンツ

• SQL MCP Server の概要
• SQL MCP Server のデータ操作ツール
• データ API ビルダー (DAB) 構成リファレンス - entities
• Data API Builder (DAB) コマンド ライン インターフェイス (CLI) リファレンス - add
• Data API Builder (DAB) コマンド ライン インターフェイス (CLI) リファレンス - update