自定义工具

除了通用的七个 DML 工具外，数据墙DBW 支持将存储过程注册为命名 MCP 自定义工具。代理在工具列表中按名称看到它们，读取描述理解用途，并直接调用——不需要通过通用的 execute_entity。

IMPORTANT

自定义工具仅适用于存储过程。表或视图实体设置 custom-tool 会导致配置错误。

注册自定义工具

在存储过程实体的 mcp 配置中设置 custom-tool: true：

bash

dab add GetProductById \
  --source "dbo.get_product_by_id" \
  --source.type "stored-procedure" \
  --permissions "anonymous:execute" \
  --mcp.custom-tool true

生成的配置：

json

{
  "GetProductById": {
    "source": {
      "type": "stored-procedure",
      "object": "dbo.get_product_by_id"
    },
    "permissions": [
      { "role": "anonymous", "actions": ["execute"] }
    ],
    "mcp": {
      "custom-tool": true
    }
  }
}

工具命名规则

自定义工具的名称由实体名转换为 snake_case：

实体名（PascalCase）	MCP 工具名（snake_case）
`GetProductById`	`get_product_by_id`
`SearchProducts`	`search_products`
`GetOrderSummary`	`get_order_summary`

代理必须使用 snake_case 名称调用工具，不能使用 PascalCase 的实体名。

添加描述提升准确性

工具描述帮助代理理解何时应该调用这个工具、它做什么：

bash

dab update GetProductById \
  --description "根据产品ID返回完整的产品详情，包含价格和库存信息"

描述会出现在 tools/list 响应的工具定义中：

json

{
  "tools": [
    {
      "name": "get_product_by_id",
      "description": "根据产品ID返回完整的产品详情，包含价格和库存信息",
      "inputSchema": {
        "type": "object",
        "properties": {}
      }
    }
  ]
}

NOTE

当前 inputSchema 仍返回空的 properties。代理通常依赖工具说明和 describe_entities 来推断正确参数。

描述越清晰，代理判断越准确。建议包含：工具的业务用途、返回什么数据、关键的筛选或限制条件。

添加参数描述

存储过程的参数描述帮助代理正确传参：

bash

dab update GetProductById \
  --parameters.name "ProductID" \
  --parameters.description "要查询的产品唯一标识符" \
  --parameters.required "true"

注册多个自定义工具

同一配置中可以注册多个存储过程作为自定义工具，各自独立命名和描述：

bash

dab add SearchProducts \
  --source dbo.search_products \
  --source.type "stored-procedure" \
  --permissions "anonymous:execute" \
  --mcp.custom-tool true \
  --description "在商品名称和描述中执行全文搜索"

dab add GetOrderSummary \
  --source dbo.get_order_summary \
  --source.type "stored-procedure" \
  --permissions "authenticated:execute" \
  --mcp.custom-tool true \
  --description "返回指定客户的订单总额和行项目数量统计"

代理会看到 search_products 和 get_order_summary 两个独立命名的工具，各自带描述和参数 —— 比通过通用 execute_entity 指定实体名更直观。

权限控制

自定义工具遵循与实体相同的 RBAC 规则：

在 permissions 中限制哪些角色可以 execute 该存储过程。
只有被授权的角色调用 tools/list 时，该自定义工具才会出现。
未授权角色尝试调用会返回权限错误。

可以为不同角色的代理暴露不同的工具集：

json

{
  "GetOrderSummary": {
    "permissions": [
      { "role": "analyst", "actions": ["execute"] }
    ]
  }
}

analyst 角色的代理能看到 get_order_summary，anonymous 角色的代理看不到。

禁用自定义工具

将 custom-tool 设为 false 可以在不删除实体的情况下隐藏工具：

bash

dab update GetProductById --mcp.custom-tool false

实体保留在配置中，REST 和 GraphQL 端点不受影响，只是从 MCP 工具列表中移除。后续需要重新暴露时，改回 true 即可。