@xihe-lab/tapd-core 2.0.0-rc.1 → 2.0.0-rc.3

package/dist/tools/bug.js

@@ -1,66 +1,67 @@
 import { z } from 'zod';
 import { TapdClient } from '../tapd-client.js';
+import { RAW_HTML_FIELD } from '../registry/richtext.js';
 export const bugTools = [
     {
         name: 'tapd_get_bugs',
-        description: 'Query TAPD bugs with filters',
+        description: '按条件查询缺陷列表，支持严重级、状态、处理人、迭代、发现/修复版本等多字段过滤与分页。只统计数量用数量统计工具；已知多个 ID 要完整详情用批量详情工具。读操作；limit 默认 30、最大 200。返回缺陷（Bug）数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('Supports multiple IDs；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            title: z.string().optional().describe('Bug title, supports fuzzy matching'),
-            priority: z.string().optional().describe('Priority, recommend using priority_label'),
-            priority_label: z.string().optional().describe('Priority (recommended)'),
-            severity: z.string().optional().describe('Severity, supports enum query'),
-            status: z.string().optional().describe('Status, supports enum query'),
-            v_status: z.string().optional().describe('Status (Chinese)'),
-            label: z.string().optional().describe('Label, supports enum query'),
-            iteration_id: z.string().optional().describe('Iteration ID, supports enum query；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            module: z.string().optional().describe('Module, supports enum query'),
-            current_owner: z.string().optional().describe('Current owner, supports fuzzy matching'),
-            reporter: z.string().optional().describe('Reporter, supports multiple users query'),
-            participator: z.string().optional().describe('Participant, supports multiple users query'),
-            te: z.string().optional().describe('Tester, supports fuzzy matching'),
-            de: z.string().optional().describe('Developer, supports fuzzy matching'),
-            cc: z.string().optional().describe('CC person'),
-            created: z.string().optional().describe('Creation time, Format: YYYY-MM-DD HH:mm'),
-            in_progress_time: z.string().optional().describe('Accept time, Format: YYYY-MM-DD HH:mm'),
-            resolved: z.string().optional().describe('Resolve time, Format: YYYY-MM-DD HH:mm'),
-            verify_time: z.string().optional().describe('Verify time, Format: YYYY-MM-DD HH:mm'),
-            closed: z.string().optional().describe('Close time, Format: YYYY-MM-DD HH:mm'),
-            reject_time: z.string().optional().describe('Reject time, Format: YYYY-MM-DD HH:mm'),
-            modified: z.string().optional().describe('Last modification time, Format: YYYY-MM-DD HH:mm'),
-            begin: z.string().optional().describe('Estimated start date, Format: YYYY-MM-DD'),
-            due: z.string().optional().describe('Estimated end date, Format: YYYY-MM-DD'),
-            deadline: z.string().optional().describe('Resolve deadline, Format: YYYY-MM-DD'),
-            release_id: z.string().optional().describe('Release plan；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            version_report: z.string().optional().describe('Found version, enum query'),
-            version_test: z.string().optional().describe('Verify version'),
-            version_fix: z.string().optional().describe('Fix version'),
-            version_close: z.string().optional().describe('Close version'),
-            baseline_find: z.string().optional().describe('Found baseline'),
-            baseline_join: z.string().optional().describe('Join baseline'),
-            baseline_test: z.string().optional().describe('Test baseline'),
-            baseline_close: z.string().optional().describe('Close baseline'),
-            feature: z.string().optional().describe('Feature'),
-            source: z.string().optional().describe('Bug root cause, supports enum query'),
-            bugtype: z.string().optional().describe('Bug type'),
-            frequency: z.string().optional().describe('Reproduction frequency, supports enum query'),
-            originphase: z.string().optional().describe('Found phase'),
-            sourcephase: z.string().optional().describe('Introduction phase'),
-            resolution: z.string().optional().describe('Resolution method, supports enum query'),
-            description: z.string().optional().describe('Detailed description, supports fuzzy matching'),
-            os: z.string().optional().describe('Operating system'),
-            platform: z.string().optional().describe('Software platform'),
-            testmode: z.string().optional().describe('Test mode'),
-            testphase: z.string().optional().describe('Test phase'),
-            testtype: z.string().optional().describe('Test type'),
-            size: z.string().optional().describe('Size'),
-            estimate: z.number().optional().describe('Estimated resolve time'),
-            custom_field_one: z.string().optional().describe('Custom field 1 (supports 1-200)'),
-            limit: z.number().optional().describe('Return count, default 30, max 200'),
-            page: z.number().optional().describe('Page number, default 1'),
-            order: z.string().optional().describe('Sort order'),
-            fields: z.string().optional().describe('Specify return fields'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('支持多 ID 查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            title: z.string().optional().describe('缺陷标题，支持模糊匹配'),
+            priority: z.string().optional().describe('优先级，建议直接用 priority_label'),
+            priority_label: z.string().optional().describe('优先级（推荐）'),
+            severity: z.string().optional().describe('严重程度，支持枚举值查询'),
+            status: z.string().optional().describe('状态，支持枚举值查询'),
+            v_status: z.string().optional().describe('状态（中文）'),
+            label: z.string().optional().describe('标签，支持枚举值查询'),
+            iteration_id: z.string().optional().describe('迭代 ID，支持枚举值查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            module: z.string().optional().describe('模块，支持枚举值查询'),
+            current_owner: z.string().optional().describe('当前处理人，支持模糊匹配'),
+            reporter: z.string().optional().describe('报告人，支持多人查询'),
+            participator: z.string().optional().describe('参与人，支持多人查询'),
+            te: z.string().optional().describe('测试人员，支持模糊匹配'),
+            de: z.string().optional().describe('开发人员，支持模糊匹配'),
+            cc: z.string().optional().describe('抄送人'),
+            created: z.string().optional().describe('创建时间，格式 YYYY-MM-DD HH:mm'),
+            in_progress_time: z.string().optional().describe('接收时间，格式 YYYY-MM-DD HH:mm'),
+            resolved: z.string().optional().describe('解决时间，格式 YYYY-MM-DD HH:mm'),
+            verify_time: z.string().optional().describe('验证时间，格式 YYYY-MM-DD HH:mm'),
+            closed: z.string().optional().describe('关闭时间，格式 YYYY-MM-DD HH:mm'),
+            reject_time: z.string().optional().describe('拒绝时间，格式 YYYY-MM-DD HH:mm'),
+            modified: z.string().optional().describe('最后修改时间，格式 YYYY-MM-DD HH:mm'),
+            begin: z.string().optional().describe('预计开始日期，格式 YYYY-MM-DD'),
+            due: z.string().optional().describe('预计结束日期，格式 YYYY-MM-DD'),
+            deadline: z.string().optional().describe('解决期限，格式 YYYY-MM-DD'),
+            release_id: z.string().optional().describe('发布计划；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            version_report: z.string().optional().describe('发现版本，枚举值查询'),
+            version_test: z.string().optional().describe('验证版本'),
+            version_fix: z.string().optional().describe('修复版本'),
+            version_close: z.string().optional().describe('关闭版本'),
+            baseline_find: z.string().optional().describe('发现基线'),
+            baseline_join: z.string().optional().describe('加入基线'),
+            baseline_test: z.string().optional().describe('测试基线'),
+            baseline_close: z.string().optional().describe('关闭基线'),
+            feature: z.string().optional().describe('特性'),
+            source: z.string().optional().describe('缺陷根源，支持枚举值查询'),
+            bugtype: z.string().optional().describe('缺陷类型'),
+            frequency: z.string().optional().describe('复现频率，支持枚举值查询'),
+            originphase: z.string().optional().describe('发现阶段'),
+            sourcephase: z.string().optional().describe('引入阶段'),
+            resolution: z.string().optional().describe('解决方法，支持枚举值查询'),
+            description: z.string().optional().describe('详细描述，支持模糊匹配'),
+            os: z.string().optional().describe('操作系统'),
+            platform: z.string().optional().describe('软件平台'),
+            testmode: z.string().optional().describe('测试方式'),
+            testphase: z.string().optional().describe('测试阶段'),
+            testtype: z.string().optional().describe('测试类型'),
+            size: z.string().optional().describe('规模'),
+            estimate: z.number().optional().describe('预计解决时长'),
+            custom_field_one: z.string().optional().describe('自定义字段 1（支持 1-200）'),
+            limit: z.number().optional().describe('返回数量，默认 30，最大 200'),
+            page: z.number().optional().describe('页码，默认 1'),
+            order: z.string().optional().describe('排序'),
+            fields: z.string().optional().describe('返回字段'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -77,56 +78,57 @@ export const bugTools = [
     },
     {
         name: 'tapd_create_bug',
-        description: 'Create a new bug in TAPD',
+        description: '创建缺陷。从已有缺陷复制用复制工具。写操作；title 必填；当前处理人/报告人缺省取环境变量 TAPD_NICK_NAME。返回新缺陷。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            title: z.string().describe('Bug title (required)'),
-            priority: z.string().optional().describe('Priority'),
-            priority_label: z.string().optional().describe('Priority label (recommended)'),
-            severity: z.string().optional().describe('Severity'),
-            current_owner: z.string().optional().describe('Current owner (defaults to TAPD_NICK_NAME env)'),
-            description: z.string().optional().describe('Detailed description'),
-            module: z.string().optional().describe('Module'),
-            iteration_id: z.string().optional().describe('Iteration ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            label: z.string().optional().describe('Label, multiple values separated by |'),
-            effort: z.number().optional().describe('Estimated effort'),
-            template_id: z.string().optional().describe('Template ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            cc: z.string().optional().describe('CC person'),
-            te: z.string().optional().describe('Tester'),
-            de: z.string().optional().describe('Developer'),
-            reporter: z.string().optional().describe('Reporter'),
-            participator: z.string().optional().describe('Participant'),
-            auditer: z.string().optional().describe('Auditor'),
-            confirmer: z.string().optional().describe('Confirmer'),
-            fixer: z.string().optional().describe('Fixer'),
-            closer: z.string().optional().describe('Closer'),
-            begin: z.string().optional().describe('Estimated start date, Format: YYYY-MM-DD'),
-            due: z.string().optional().describe('Estimated end date, Format: YYYY-MM-DD'),
-            deadline: z.string().optional().describe('Resolve deadline, Format: YYYY-MM-DD'),
-            release_id: z.string().optional().describe('Release plan；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            version_report: z.string().optional().describe('Found version'),
-            version_test: z.string().optional().describe('Verify version'),
-            version_fix: z.string().optional().describe('Fix version'),
-            version_close: z.string().optional().describe('Close version'),
-            baseline_find: z.string().optional().describe('Found baseline'),
-            baseline_join: z.string().optional().describe('Join baseline'),
-            baseline_test: z.string().optional().describe('Test baseline'),
-            baseline_close: z.string().optional().describe('Close baseline'),
-            feature: z.string().optional().describe('Feature'),
-            source: z.string().optional().describe('Bug root cause'),
-            bugtype: z.string().optional().describe('Bug type'),
-            frequency: z.string().optional().describe('Reproduction frequency'),
-            originphase: z.string().optional().describe('Found phase'),
-            sourcephase: z.string().optional().describe('Introduction phase'),
-            resolution: z.string().optional().describe('Resolution method'),
-            os: z.string().optional().describe('Operating system'),
-            platform: z.string().optional().describe('Software platform'),
-            testmode: z.string().optional().describe('Test mode'),
-            testphase: z.string().optional().describe('Test phase'),
-            testtype: z.string().optional().describe('Test type'),
-            size: z.string().optional().describe('Size'),
-            estimate: z.number().optional().describe('Estimated resolve time'),
-            custom_field_one: z.string().optional().describe('Custom field 1 (supports 1-200)'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            title: z.string().describe('缺陷标题（必填）'),
+            priority: z.string().optional().describe('优先级'),
+            priority_label: z.string().optional().describe('优先级标签（推荐）'),
+            severity: z.string().optional().describe('严重程度'),
+            current_owner: z.string().optional().describe('当前处理人（缺省取环境变量 TAPD_NICK_NAME）'),
+            description: z.string().optional().describe('详细描述'),
+            raw_html: RAW_HTML_FIELD,
+            module: z.string().optional().describe('模块'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            label: z.string().optional().describe('标签，多个以 | 分隔'),
+            effort: z.number().optional().describe('预估工时'),
+            template_id: z.string().optional().describe('模板 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            cc: z.string().optional().describe('抄送人'),
+            te: z.string().optional().describe('测试人员'),
+            de: z.string().optional().describe('开发人员'),
+            reporter: z.string().optional().describe('报告人'),
+            participator: z.string().optional().describe('参与人'),
+            auditer: z.string().optional().describe('审核人'),
+            confirmer: z.string().optional().describe('确认人'),
+            fixer: z.string().optional().describe('修复人'),
+            closer: z.string().optional().describe('关闭人'),
+            begin: z.string().optional().describe('预计开始日期，格式 YYYY-MM-DD'),
+            due: z.string().optional().describe('预计结束日期，格式 YYYY-MM-DD'),
+            deadline: z.string().optional().describe('解决期限，格式 YYYY-MM-DD'),
+            release_id: z.string().optional().describe('发布计划；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            version_report: z.string().optional().describe('发现版本'),
+            version_test: z.string().optional().describe('验证版本'),
+            version_fix: z.string().optional().describe('修复版本'),
+            version_close: z.string().optional().describe('关闭版本'),
+            baseline_find: z.string().optional().describe('发现基线'),
+            baseline_join: z.string().optional().describe('加入基线'),
+            baseline_test: z.string().optional().describe('测试基线'),
+            baseline_close: z.string().optional().describe('关闭基线'),
+            feature: z.string().optional().describe('特性'),
+            source: z.string().optional().describe('缺陷根源'),
+            bugtype: z.string().optional().describe('缺陷类型'),
+            frequency: z.string().optional().describe('复现频率'),
+            originphase: z.string().optional().describe('发现阶段'),
+            sourcephase: z.string().optional().describe('引入阶段'),
+            resolution: z.string().optional().describe('解决方法'),
+            os: z.string().optional().describe('操作系统'),
+            platform: z.string().optional().describe('软件平台'),
+            testmode: z.string().optional().describe('测试方式'),
+            testphase: z.string().optional().describe('测试阶段'),
+            testtype: z.string().optional().describe('测试类型'),
+            size: z.string().optional().describe('规模'),
+            estimate: z.number().optional().describe('预计解决时长'),
+            custom_field_one: z.string().optional().describe('自定义字段 1（支持 1-200）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -145,53 +147,54 @@ export const bugTools = [
     },
     {
         name: 'tapd_update_bug',
-        description: 'Update an existing bug in TAPD',
+        description: '按 ID 更新缺陷字段（状态流转、处理人、解决期限等）。批量改多条用批量更新工具。写操作；id 必填。返回更新后的缺陷。',
         inputSchema: z.object({
-            id: z.string().describe('Bug ID (required)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            title: z.string().optional().describe('Bug title'),
-            priority: z.string().optional().describe('Priority'),
-            priority_label: z.string().optional().describe('Priority label (recommended)'),
-            severity: z.string().optional().describe('Severity'),
-            status: z.string().optional().describe('Status'),
-            current_owner: z.string().optional().describe('Current owner'),
-            description: z.string().optional().describe('Detailed description'),
-            module: z.string().optional().describe('Module'),
-            iteration_id: z.string().optional().describe('Iteration ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            label: z.string().optional().describe('Label, multiple values separated by |'),
-            effort: z.number().optional().describe('Estimated effort'),
-            cc: z.string().optional().describe('CC person'),
-            te: z.string().optional().describe('Tester'),
-            de: z.string().optional().describe('Developer'),
-            reporter: z.string().optional().describe('Reporter'),
-            participator: z.string().optional().describe('Participant'),
-            begin: z.string().optional().describe('Estimated start date, Format: YYYY-MM-DD'),
-            due: z.string().optional().describe('Estimated end date, Format: YYYY-MM-DD'),
-            deadline: z.string().optional().describe('Resolve deadline, Format: YYYY-MM-DD'),
-            release_id: z.string().optional().describe('Release plan；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            version_report: z.string().optional().describe('Found version'),
-            version_test: z.string().optional().describe('Verify version'),
-            version_fix: z.string().optional().describe('Fix version'),
-            version_close: z.string().optional().describe('Close version'),
-            baseline_find: z.string().optional().describe('Found baseline'),
-            baseline_join: z.string().optional().describe('Join baseline'),
-            baseline_test: z.string().optional().describe('Test baseline'),
-            baseline_close: z.string().optional().describe('Close baseline'),
-            feature: z.string().optional().describe('Feature'),
-            source: z.string().optional().describe('Bug root cause'),
-            bugtype: z.string().optional().describe('Bug type'),
-            frequency: z.string().optional().describe('Reproduction frequency'),
-            originphase: z.string().optional().describe('Found phase'),
-            sourcephase: z.string().optional().describe('Introduction phase'),
-            resolution: z.string().optional().describe('Resolution method'),
-            os: z.string().optional().describe('Operating system'),
-            platform: z.string().optional().describe('Software platform'),
-            testmode: z.string().optional().describe('Test mode'),
-            testphase: z.string().optional().describe('Test phase'),
-            testtype: z.string().optional().describe('Test type'),
-            size: z.string().optional().describe('Size'),
-            estimate: z.number().optional().describe('Estimated resolve time'),
-            custom_field_one: z.string().optional().describe('Custom field 1 (supports 1-200)'),
+            id: z.string().describe('缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            title: z.string().optional().describe('缺陷标题'),
+            priority: z.string().optional().describe('优先级'),
+            priority_label: z.string().optional().describe('优先级标签（推荐）'),
+            severity: z.string().optional().describe('严重程度'),
+            status: z.string().optional().describe('状态'),
+            current_owner: z.string().optional().describe('当前处理人'),
+            description: z.string().optional().describe('详细描述'),
+            raw_html: RAW_HTML_FIELD,
+            module: z.string().optional().describe('模块'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            label: z.string().optional().describe('标签，多个以 | 分隔'),
+            effort: z.number().optional().describe('预估工时'),
+            cc: z.string().optional().describe('抄送人'),
+            te: z.string().optional().describe('测试人员'),
+            de: z.string().optional().describe('开发人员'),
+            reporter: z.string().optional().describe('报告人'),
+            participator: z.string().optional().describe('参与人'),
+            begin: z.string().optional().describe('预计开始日期，格式 YYYY-MM-DD'),
+            due: z.string().optional().describe('预计结束日期，格式 YYYY-MM-DD'),
+            deadline: z.string().optional().describe('解决期限，格式 YYYY-MM-DD'),
+            release_id: z.string().optional().describe('发布计划；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            version_report: z.string().optional().describe('发现版本'),
+            version_test: z.string().optional().describe('验证版本'),
+            version_fix: z.string().optional().describe('修复版本'),
+            version_close: z.string().optional().describe('关闭版本'),
+            baseline_find: z.string().optional().describe('发现基线'),
+            baseline_join: z.string().optional().describe('加入基线'),
+            baseline_test: z.string().optional().describe('测试基线'),
+            baseline_close: z.string().optional().describe('关闭基线'),
+            feature: z.string().optional().describe('特性'),
+            source: z.string().optional().describe('缺陷根源'),
+            bugtype: z.string().optional().describe('缺陷类型'),
+            frequency: z.string().optional().describe('复现频率'),
+            originphase: z.string().optional().describe('发现阶段'),
+            sourcephase: z.string().optional().describe('引入阶段'),
+            resolution: z.string().optional().describe('解决方法'),
+            os: z.string().optional().describe('操作系统'),
+            platform: z.string().optional().describe('软件平台'),
+            testmode: z.string().optional().describe('测试方式'),
+            testphase: z.string().optional().describe('测试阶段'),
+            testtype: z.string().optional().describe('测试类型'),
+            size: z.string().optional().describe('规模'),
+            estimate: z.number().optional().describe('预计解决时长'),
+            custom_field_one: z.string().optional().describe('自定义字段 1（支持 1-200）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -208,60 +211,60 @@ export const bugTools = [
     },
     {
         name: 'tapd_get_bug_count',
-        description: 'Get the count of bugs matching filters',
+        description: '按与缺陷列表查询相同的过滤条件返回缺陷数量，不返回列表。统计缺陷存量/趋势时用。读操作。返回 {count}。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('Supports multiple IDs；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            title: z.string().optional().describe('Bug title, supports fuzzy matching'),
-            priority: z.string().optional().describe('Priority, recommend using priority_label'),
-            priority_label: z.string().optional().describe('Priority (recommended)'),
-            severity: z.string().optional().describe('Severity, supports enum query'),
-            status: z.string().optional().describe('Status, supports enum query'),
-            v_status: z.string().optional().describe('Status (Chinese)'),
-            label: z.string().optional().describe('Label, supports enum query'),
-            iteration_id: z.string().optional().describe('Iteration ID, supports enum query；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            module: z.string().optional().describe('Module, supports enum query'),
-            current_owner: z.string().optional().describe('Current owner, supports fuzzy matching'),
-            reporter: z.string().optional().describe('Reporter, supports multiple users query'),
-            participator: z.string().optional().describe('Participant, supports multiple users query'),
-            te: z.string().optional().describe('Tester, supports fuzzy matching'),
-            de: z.string().optional().describe('Developer, supports fuzzy matching'),
-            cc: z.string().optional().describe('CC person'),
-            created: z.string().optional().describe('Creation time, Format: YYYY-MM-DD HH:mm'),
-            in_progress_time: z.string().optional().describe('Accept time, Format: YYYY-MM-DD HH:mm'),
-            resolved: z.string().optional().describe('Resolve time, Format: YYYY-MM-DD HH:mm'),
-            verify_time: z.string().optional().describe('Verify time, Format: YYYY-MM-DD HH:mm'),
-            closed: z.string().optional().describe('Close time, Format: YYYY-MM-DD HH:mm'),
-            reject_time: z.string().optional().describe('Reject time, Format: YYYY-MM-DD HH:mm'),
-            modified: z.string().optional().describe('Last modification time, Format: YYYY-MM-DD HH:mm'),
-            begin: z.string().optional().describe('Estimated start date, Format: YYYY-MM-DD'),
-            due: z.string().optional().describe('Estimated end date, Format: YYYY-MM-DD'),
-            deadline: z.string().optional().describe('Resolve deadline, Format: YYYY-MM-DD'),
-            release_id: z.string().optional().describe('Release plan；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            version_report: z.string().optional().describe('Found version, enum query'),
-            version_test: z.string().optional().describe('Verify version'),
-            version_fix: z.string().optional().describe('Fix version'),
-            version_close: z.string().optional().describe('Close version'),
-            baseline_find: z.string().optional().describe('Found baseline'),
-            baseline_join: z.string().optional().describe('Join baseline'),
-            baseline_test: z.string().optional().describe('Test baseline'),
-            baseline_close: z.string().optional().describe('Close baseline'),
-            feature: z.string().optional().describe('Feature'),
-            source: z.string().optional().describe('Bug root cause, supports enum query'),
-            bugtype: z.string().optional().describe('Bug type'),
-            frequency: z.string().optional().describe('Reproduction frequency, supports enum query'),
-            originphase: z.string().optional().describe('Found phase'),
-            sourcephase: z.string().optional().describe('Introduction phase'),
-            resolution: z.string().optional().describe('Resolution method, supports enum query'),
-            description: z.string().optional().describe('Detailed description, supports fuzzy matching'),
-            os: z.string().optional().describe('Operating system'),
-            platform: z.string().optional().describe('Software platform'),
-            testmode: z.string().optional().describe('Test mode'),
-            testphase: z.string().optional().describe('Test phase'),
-            testtype: z.string().optional().describe('Test type'),
-            size: z.string().optional().describe('Size'),
-            estimate: z.number().optional().describe('Estimated resolve time'),
-            custom_field_one: z.string().optional().describe('Custom field 1 (supports 1-200)'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('支持多 ID 查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            title: z.string().optional().describe('缺陷标题，支持模糊匹配'),
+            priority: z.string().optional().describe('优先级，建议直接用 priority_label'),
+            priority_label: z.string().optional().describe('优先级（推荐）'),
+            severity: z.string().optional().describe('严重程度，支持枚举值查询'),
+            status: z.string().optional().describe('状态，支持枚举值查询'),
+            v_status: z.string().optional().describe('状态（中文）'),
+            label: z.string().optional().describe('标签，支持枚举值查询'),
+            iteration_id: z.string().optional().describe('迭代 ID，支持枚举值查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            module: z.string().optional().describe('模块，支持枚举值查询'),
+            current_owner: z.string().optional().describe('当前处理人，支持模糊匹配'),
+            reporter: z.string().optional().describe('报告人，支持多人查询'),
+            participator: z.string().optional().describe('参与人，支持多人查询'),
+            te: z.string().optional().describe('测试人员，支持模糊匹配'),
+            de: z.string().optional().describe('开发人员，支持模糊匹配'),
+            cc: z.string().optional().describe('抄送人'),
+            created: z.string().optional().describe('创建时间，格式 YYYY-MM-DD HH:mm'),
+            in_progress_time: z.string().optional().describe('接收时间，格式 YYYY-MM-DD HH:mm'),
+            resolved: z.string().optional().describe('解决时间，格式 YYYY-MM-DD HH:mm'),
+            verify_time: z.string().optional().describe('验证时间，格式 YYYY-MM-DD HH:mm'),
+            closed: z.string().optional().describe('关闭时间，格式 YYYY-MM-DD HH:mm'),
+            reject_time: z.string().optional().describe('拒绝时间，格式 YYYY-MM-DD HH:mm'),
+            modified: z.string().optional().describe('最后修改时间，格式 YYYY-MM-DD HH:mm'),
+            begin: z.string().optional().describe('预计开始日期，格式 YYYY-MM-DD'),
+            due: z.string().optional().describe('预计结束日期，格式 YYYY-MM-DD'),
+            deadline: z.string().optional().describe('解决期限，格式 YYYY-MM-DD'),
+            release_id: z.string().optional().describe('发布计划；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            version_report: z.string().optional().describe('发现版本，枚举值查询'),
+            version_test: z.string().optional().describe('验证版本'),
+            version_fix: z.string().optional().describe('修复版本'),
+            version_close: z.string().optional().describe('关闭版本'),
+            baseline_find: z.string().optional().describe('发现基线'),
+            baseline_join: z.string().optional().describe('加入基线'),
+            baseline_test: z.string().optional().describe('测试基线'),
+            baseline_close: z.string().optional().describe('关闭基线'),
+            feature: z.string().optional().describe('特性'),
+            source: z.string().optional().describe('缺陷根源，支持枚举值查询'),
+            bugtype: z.string().optional().describe('缺陷类型'),
+            frequency: z.string().optional().describe('复现频率，支持枚举值查询'),
+            originphase: z.string().optional().describe('发现阶段'),
+            sourcephase: z.string().optional().describe('引入阶段'),
+            resolution: z.string().optional().describe('解决方法，支持枚举值查询'),
+            description: z.string().optional().describe('详细描述，支持模糊匹配'),
+            os: z.string().optional().describe('操作系统'),
+            platform: z.string().optional().describe('软件平台'),
+            testmode: z.string().optional().describe('测试方式'),
+            testphase: z.string().optional().describe('测试阶段'),
+            testtype: z.string().optional().describe('测试类型'),
+            size: z.string().optional().describe('规模'),
+            estimate: z.number().optional().describe('预计解决时长'),
+            custom_field_one: z.string().optional().describe('自定义字段 1（支持 1-200）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -279,18 +282,18 @@ export const bugTools = [
     // 缺陷变更历史
     {
         name: 'tapd_get_bug_changes',
-        description: '获取缺陷变更历史',
+        description: '查询缺陷字段变更历史（谁在何时把什么字段从什么改成什么）。只要条数用变更次数统计工具。读操作；limit 默认 30、最大 200。返回变更记录数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('变更记录ID，支持多ID查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            bug_id: z.string().optional().describe('缺陷ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('变更记录 ID，支持多 ID查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            bug_id: z.string().optional().describe('缺陷 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             field: z.string().optional().describe('变更字段'),
             value_before: z.string().optional().describe('变更前值'),
             value_after: z.string().optional().describe('变更后值'),
             user: z.string().optional().describe('变更人'),
             created: z.string().optional().describe('创建时间，支持时间查询'),
-            limit: z.number().optional().describe('返回数量，默认30，最大200'),
-            page: z.number().optional().describe('页码，默认1'),
+            limit: z.number().optional().describe('返回数量，默认 30，最大 200'),
+            page: z.number().optional().describe('页码，默认 1'),
             order: z.string().optional().describe('排序'),
             fields: z.string().optional().describe('返回字段'),
         }),
@@ -309,10 +312,10 @@ export const bugTools = [
     },
     {
         name: 'tapd_get_bug_changes_count',
-        description: '获取缺陷变更次数',
+        description: '按过滤条件返回缺陷变更记录条数。要看明细用变更历史查询工具。读操作。返回 {count}。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            bug_id: z.string().optional().describe('缺陷ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            bug_id: z.string().optional().describe('缺陷 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             field: z.string().optional().describe('变更字段'),
             user: z.string().optional().describe('变更人'),
             created: z.string().optional().describe('创建时间'),
@@ -333,9 +336,9 @@ export const bugTools = [
     // 缺陷字段配置
     {
         name: 'tapd_get_bug_custom_fields_settings',
-        description: '获取缺陷自定义字段配置',
+        description: '查询缺陷自定义字段配置（字段名、类型、候选值）。需求侧用需求自定义字段查询工具。读操作。返回配置数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -347,9 +350,9 @@ export const bugTools = [
     },
     {
         name: 'tapd_get_bug_fields_info',
-        description: '获取缺陷字段信息',
+        description: '查询缺陷可写字段元信息（类型、是否必填）。读操作。返回字段定义数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -361,9 +364,9 @@ export const bugTools = [
     },
     {
         name: 'tapd_get_bug_fields_lable',
-        description: '获取缺陷字段中英文对照',
+        description: '查询缺陷字段名中英文对照。读操作。返回映射对象。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -376,9 +379,9 @@ export const bugTools = [
     // 缺陷模板
     {
         name: 'tapd_get_bug_template_list',
-        description: '获取缺陷模板列表',
+        description: '查询缺陷模板列表。取默认模板用默认模板查询工具。读操作。返回模板数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
             limit: z.number().optional().describe('返回数量'),
             page: z.number().optional().describe('页码'),
             fields: z.string().optional().describe('返回字段'),
@@ -393,9 +396,9 @@ export const bugTools = [
     },
     {
         name: 'tapd_get_default_bug_template',
-        description: '获取缺陷默认模板',
+        description: '查询缺陷默认模板字段。要模板清单用模板列表查询工具。读操作。返回默认模板。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -408,10 +411,10 @@ export const bugTools = [
     // 批量操作
     {
         name: 'tapd_batch_update_bugs',
-        description: '批量更新缺陷',
+        description: '一次批量更新最多 50 条缺陷（处理器内自动做长 ID 转换）。只改一条用单条更新工具。写操作；bugs 传 JSON 数组字符串。返回批量结果。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            bugs: z.string().describe('缺陷更新数组JSON，最多50条 (必填)'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            bugs: z.string().describe('缺陷更新数组JSON，最多50条（必填）'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -438,15 +441,15 @@ export const bugTools = [
     },
     {
         name: 'tapd_copy_bug',
-        description: '复制缺陷',
+        description: '复制已有缺陷创建新缺陷，可选带附件、评论。从零新建用创建工具。写操作；id 必填。返回新缺陷。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().describe('要复制的缺陷ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().describe('要复制的缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             title: z.string().optional().describe('新缺陷标题（默认为原标题）'),
             current_owner: z.string().optional().describe('处理人'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            copy_attachments: z.number().optional().describe('是否复制附件，值=1复制'),
-            copy_comments: z.number().optional().describe('是否复制评论，值=1复制'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            copy_attachments: z.number().optional().describe('是否复制附件，值=1 为复制'),
+            copy_comments: z.number().optional().describe('是否复制评论，值=1 为复制'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -464,10 +467,10 @@ export const bugTools = [
     // 缺陷关联
     {
         name: 'tapd_get_link_bugs',
-        description: '获取缺陷关联关系',
+        description: '查询某缺陷的缺陷间关联关系。建立/取消关联用关联建立/取消工具；查缺陷关联的需求用关联需求查询工具。读操作；bug_id 必填。返回关联数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            bug_id: z.string().describe('缺陷ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            bug_id: z.string().describe('缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -484,11 +487,11 @@ export const bugTools = [
     },
     {
         name: 'tapd_link_bugs',
-        description: '关联缺陷',
+        description: '建立缺陷与缺陷的关联（可标前置/后置等类型）。查询用关联关系查询工具；取消用关联取消工具。写操作；bug_id（主缺陷）与被关联缺陷 ID 必填。返回关联结果。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            bug_id: z.string().describe('主缺陷ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            link_bug_id: z.string().describe('关联缺陷ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            bug_id: z.string().describe('主缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            link_bug_id: z.string().describe('关联缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             link_type: z.string().optional().describe('关联类型（前置/后置等）'),
         }),
         handler: async (client, params) => {
@@ -507,11 +510,11 @@ export const bugTools = [
     },
     {
         name: 'tapd_delete_link_bugs',
-        description: '取消关联缺陷',
+        description: '取消缺陷与缺陷的关联。建立关联用关联建立工具。写操作；bug_id、被取消关联的缺陷 ID 必填。返回解除结果。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            bug_id: z.string().describe('主缺陷ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            link_bug_id: z.string().describe('要取消关联的缺陷ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            bug_id: z.string().describe('主缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            link_bug_id: z.string().describe('要取消关联的缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -529,10 +532,10 @@ export const bugTools = [
     },
     {
         name: 'tapd_get_related_stories',
-        description: '获取缺陷关联需求',
+        description: '查询缺陷关联的需求。反向（按需求找缺陷）用需求侧关联缺陷查询工具；缺陷间关联用缺陷关联关系查询工具。读操作；bug_id 必填。返回关联需求。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            bug_id: z.string().describe('缺陷ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            bug_id: z.string().describe('缺陷 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -550,12 +553,12 @@ export const bugTools = [
     // 其他
     {
         name: 'tapd_get_bugs_by_view_conf_id',
-        description: '获取视图缺陷列表',
+        description: '按视图配置 ID 查询该视图下的缺陷列表。自定义条件查询用列表查询工具。读操作；view_conf_id 必填。返回缺陷列表。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            view_conf_id: z.string().describe('视图配置ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            limit: z.number().optional().describe('返回数量，默认30，最大200'),
-            page: z.number().optional().describe('页码，默认1'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            view_conf_id: z.string().describe('视图配置 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            limit: z.number().optional().describe('返回数量，默认 30，最大 200'),
+            page: z.number().optional().describe('页码，默认 1'),
             fields: z.string().optional().describe('返回字段'),
         }),
         handler: async (client, params) => {
@@ -568,16 +571,16 @@ export const bugTools = [
     },
     {
         name: 'tapd_get_removed_bugs',
-        description: '获取回收站缺陷',
+        description: '查询回收站中的缺陷。存续缺陷用列表查询工具。读操作；limit 默认 30、最大 200。返回已删除缺陷数组。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('缺陷ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('缺陷 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             title: z.string().optional().describe('标题'),
             current_owner: z.string().optional().describe('处理人'),
             reporter: z.string().optional().describe('创建人'),
             created: z.string().optional().describe('创建时间'),
             deleted: z.string().optional().describe('删除时间'),
-            limit: z.number().optional().describe('返回数量，默认30，最大200'),
+            limit: z.number().optional().describe('返回数量，默认 30，最大 200'),
             page: z.number().optional().describe('页码'),
             order: z.string().optional().describe('排序'),
             fields: z.string().optional().describe('返回字段'),
@@ -597,10 +600,10 @@ export const bugTools = [
     },
     {
         name: 'tapd_bug_ids_to_query_token',
-        description: '转换缺陷ID为queryToken',
+        description: '把一批缺陷 ID 转成服务端 queryToken（供按 ID 集合查询的场景）。仅做 ID→token 转换；要完整详情用批量详情工具。读操作；ids 逗号分隔。返回 queryToken。',
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            ids: z.string().describe('缺陷ID列表，逗号分隔 (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            ids: z.string().describe('缺陷 ID列表，逗号分隔（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();