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

package/dist/tools/test.js

@@ -4,11 +4,11 @@ export const testTools = [
     // 测试用例 CRUD
     {
         name: "tapd_create_test_case",
-        description: "创建测试用例",
+        description: "创建测试用例（名称、步骤、预期结果、前置条件）。写操作；name 必填；创建人缺省取环境变量 TAPD_NICK_NAME。返回新用例。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            name: z.string().describe("测试用例名称 (必填)"),
-            category_id: z.string().optional().describe('分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            name: z.string().describe("测试用例名称（必填）"),
+            category_id: z.string().optional().describe('分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             priority: z.string().optional().describe("优先级"),
             status: z.string().optional().describe("状态: updating/abandon/normal"),
             description: z.string().optional().describe("描述"),
@@ -16,9 +16,9 @@ export const testTools = [
             expectresult: z.string().optional().describe("预期结果"),
             precondition: z.string().optional().describe("前置条件"),
             type: z.string().optional().describe("用例类型"),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             owner: z.string().optional().describe("负责人"),
-            creator: z.string().optional().describe("创建人（默认当前用户）"),
+            creator: z.string().optional().describe("创建人（缺省取当前用户）"),
             custom_field_one: z.string().optional().describe("自定义字段 (支持 1-200)"),
         }),
         handler: async (client, params) => {
@@ -37,22 +37,22 @@ export const testTools = [
     },
     {
         name: "tapd_get_test_cases",
-        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 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('测试用例 ID，支持多 ID查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             name: z.string().optional().describe("测试用例名称，支持模糊匹配"),
             status: z.string().optional().describe("状态: updating/abandon/normal"),
             priority: z.string().optional().describe("优先级"),
-            category_id: z.string().optional().describe('分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            category_id: z.string().optional().describe('分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             creator: z.string().optional().describe("创建人"),
             owner: z.string().optional().describe("负责人"),
             created: z.string().optional().describe("创建时间，支持时间查询"),
             modified: z.string().optional().describe("修改时间，支持时间查询"),
             custom_field_one: 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("返回字段"),
         }),
@@ -66,15 +66,15 @@ export const testTools = [
     },
     {
         name: "tapd_get_test_cases_count",
-        description: "获取测试用例数量",
+        description: "按相同过滤条件返回测试用例数量。要看列表用用例列表查询工具。读操作。返回 {count}。",
         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 安全整数范围会丢精度'),
             name: z.string().optional().describe("测试用例名称"),
             status: z.string().optional().describe("状态"),
             priority: z.string().optional().describe("优先级"),
-            category_id: z.string().optional().describe('分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            category_id: z.string().optional().describe('分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             creator: z.string().optional().describe("创建人"),
             owner: z.string().optional().describe("负责人"),
         }),
@@ -88,20 +88,20 @@ export const testTools = [
     },
     {
         name: "tapd_update_test_case",
-        description: "更新测试用例",
+        description: "按 ID 更新测试用例（步骤、预期结果、状态等）。写操作；id 必填。返回更新结果。",
         inputSchema: z.object({
-            id: z.string().describe('测试用例ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            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）'),
             name: z.string().optional().describe("测试用例名称"),
             status: z.string().optional().describe("状态"),
             priority: z.string().optional().describe("优先级"),
-            category_id: z.string().optional().describe('分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            category_id: z.string().optional().describe('分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             description: z.string().optional().describe("描述"),
             teststeps: z.string().optional().describe("测试步骤"),
             expectresult: z.string().optional().describe("预期结果"),
             precondition: z.string().optional().describe("前置条件"),
             type: z.string().optional().describe("用例类型"),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             owner: z.string().optional().describe("负责人"),
             custom_field_one: z.string().optional().describe("自定义字段"),
         }),
@@ -116,12 +116,12 @@ export const testTools = [
     // 测试用例分类
     {
         name: "tapd_get_tcase_categories",
-        description: "获取测试用例分类列表",
+        description: "查询测试用例分类列表。只统计数量用数量统计工具。读操作。返回分类数组。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            id: z.string().optional().describe('分类ID，支持多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 安全整数范围会丢精度'),
             name: z.string().optional().describe("分类名称，支持模糊匹配"),
-            parent_id: z.string().optional().describe("父分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度"),
+            parent_id: z.string().optional().describe("父分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度"),
             created: z.string().optional().describe("创建时间"),
             modified: z.string().optional().describe("修改时间"),
             limit: z.number().optional().describe("返回数量"),
@@ -139,12 +139,12 @@ export const testTools = [
     },
     {
         name: "tapd_get_tcase_categories_count",
-        description: "获取测试用例分类数量",
+        description: "按相同过滤条件返回用例分类数量。要看列表用分类列表查询工具。读操作。返回 {count}。",
         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 安全整数范围会丢精度'),
             name: z.string().optional().describe("分类名称"),
-            parent_id: z.string().optional().describe("父分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度"),
+            parent_id: z.string().optional().describe("父分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度"),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -156,11 +156,11 @@ export const testTools = [
     },
     {
         name: "tapd_add_tcase_category",
-        description: "创建测试用例分类",
+        description: "创建测试用例分类，可挂父分类。写操作；name 必填。返回新分类。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            name: z.string().describe("分类名称 (必填)"),
-            parent_id: z.string().optional().describe("父分类ID（用于创建子分类）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度"),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            name: z.string().describe("分类名称（必填）"),
+            parent_id: z.string().optional().describe("父分类 ID（用于创建子分类）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度"),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -173,9 +173,9 @@ export const testTools = [
     // 测试用例配置
     {
         name: "tapd_get_tcase_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();
@@ -187,9 +187,9 @@ export const testTools = [
     },
     {
         name: "tapd_get_tcase_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();
@@ -201,10 +201,10 @@ export const testTools = [
     },
     {
         name: "tapd_get_story_by_tcase_id",
-        description: "获取测试用例关联的需求",
+        description: "按测试用例 ID 反查其关联的需求。正向（按需求找用例）用需求侧关联用例查询工具。读操作；tcase_id 必填。返回关联需求。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            tcase_id: z.string().describe('测试用例ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            tcase_id: z.string().describe('测试用例 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -217,12 +217,12 @@ export const testTools = [
     // 测试用例执行
     {
         name: "tapd_assign_tcase_instance",
-        description: "分配测试用例执行人",
+        description: "在测试计划内给用例实例分配执行人。执行用例用用例执行工具。写操作；test_plan_id、tcase_id、owner 必填。返回分配结果。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            tcase_id: z.string().describe('测试用例ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            owner: z.string().describe("分配的执行人 (必填)"),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            tcase_id: z.string().describe('测试用例 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            owner: z.string().describe("分配的执行人（必填）"),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -234,16 +234,16 @@ export const testTools = [
     },
     {
         name: "tapd_execute_tcase_instance",
-        description: "执行测试用例",
+        description: "执行测试计划中的用例并记录结果（pass/fail/block），可带逐步骤结果、实际结果与关联缺陷。分配执行人用执行人分配工具。写操作；tcase_id、test_plan_id、result 必填。返回执行结果。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            tcase_id: z.string().describe('测试用例ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            result: z.string().describe("执行结果 (必填): pass/fail/block"),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            tcase_id: z.string().describe('测试用例 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            result: z.string().describe("执行结果（必填）: pass/fail/block"),
             run_step: z.string().optional().describe("执行步骤结果（JSON格式）"),
             actual_result: z.string().optional().describe("实际结果"),
-            bug_id: z.string().optional().describe('关联缺陷ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            executed_by: z.string().optional().describe("执行人（默认当前用户）"),
+            bug_id: z.string().optional().describe('关联缺陷 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            executed_by: z.string().optional().describe("执行人（缺省取当前用户）"),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -255,11 +255,11 @@ export const testTools = [
     },
     {
         name: "tapd_get_tcase_result",
-        description: "获取测试用例执行结果",
+        description: "查询用例执行结果记录（可按计划、结果、执行人过滤）。写侧执行动作用用例执行工具。读操作。返回结果数组。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            tcase_id: z.string().optional().describe('测试用例ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            test_plan_id: z.string().optional().describe('测试计划ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            tcase_id: z.string().optional().describe('测试用例 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            test_plan_id: z.string().optional().describe('测试计划 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             result: z.string().optional().describe("执行结果: pass/fail/block"),
             executed_by: z.string().optional().describe("执行人"),
             executed: z.string().optional().describe("执行时间"),
@@ -277,11 +277,11 @@ export const testTools = [
     },
     {
         name: "tapd_remove_tcase_instance",
-        description: "测试用例移出测试计划",
+        description: "把测试用例移出测试计划。加入计划用计划侧用例关联工具。写操作；test_plan_id、tcase_id 必填。返回移除结果。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            tcase_id: z.string().describe('测试用例ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            tcase_id: z.string().describe('测试用例 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -293,11 +293,11 @@ export const testTools = [
     },
     {
         name: "tapd_delete_tcase_story_relation",
-        description: "解除测试用例与需求关联",
+        description: "解除测试用例与需求的关联。建立关联用需求侧用例关联建立工具。写操作；tcase_id、story_id 必填。返回解除结果。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            tcase_id: z.string().describe('测试用例ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            story_id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            tcase_id: z.string().describe('测试用例 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            story_id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -310,10 +310,10 @@ export const testTools = [
     // 测试计划 CRUD
     {
         name: "tapd_get_test_plans",
-        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 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            id: z.string().optional().describe('测试计划 ID，支持多 ID查询；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             name: z.string().optional().describe("测试计划名称，支持模糊匹配"),
             status: z.string().optional().describe("状态"),
             creator: z.string().optional().describe("创建人"),
@@ -322,9 +322,9 @@ export const testTools = [
             end: z.string().optional().describe("结束日期"),
             created: z.string().optional().describe("创建时间"),
             modified: z.string().optional().describe("修改时间"),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            limit: z.number().optional().describe("返回数量，默认30，最大200"),
-            page: z.number().optional().describe("页码，默认1"),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            limit: z.number().optional().describe("返回数量，默认 30，最大 200"),
+            page: z.number().optional().describe("页码，默认 1"),
             order: z.string().optional().describe("排序"),
             fields: z.string().optional().describe("返回字段"),
         }),
@@ -338,18 +338,18 @@ export const testTools = [
     },
     {
         name: "tapd_create_test_plan",
-        description: "创建测试计划",
+        description: "创建测试计划。写操作；name 必填；负责人/创建人缺省取环境变量 TAPD_NICK_NAME。返回新计划。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            name: z.string().describe("测试计划名称 (必填)"),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            name: z.string().describe("测试计划名称（必填）"),
             description: z.string().optional().describe("描述"),
-            owner: z.string().optional().describe("负责人（默认当前用户）"),
-            creator: z.string().optional().describe("创建人（默认当前用户）"),
+            owner: z.string().optional().describe("负责人（缺省取当前用户）"),
+            creator: z.string().optional().describe("创建人（缺省取当前用户）"),
             begin: z.string().optional().describe("开始日期 (YYYY-MM-DD)"),
             end: z.string().optional().describe("结束日期 (YYYY-MM-DD)"),
             status: z.string().optional().describe("状态"),
-            category_id: z.string().optional().describe('分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            category_id: z.string().optional().describe('分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -368,18 +368,18 @@ export const testTools = [
     },
     {
         name: "tapd_update_test_plan",
-        description: "更新测试计划",
+        description: "按 ID 更新测试计划。写操作；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 安全整数范围会丢精度'),
             name: z.string().optional().describe("测试计划名称"),
             description: z.string().optional().describe("描述"),
             owner: z.string().optional().describe("负责人"),
             begin: z.string().optional().describe("开始日期 (YYYY-MM-DD)"),
             end: z.string().optional().describe("结束日期 (YYYY-MM-DD)"),
             status: z.string().optional().describe("状态"),
-            category_id: z.string().optional().describe('分类ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            iteration_id: z.string().optional().describe('迭代ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            category_id: z.string().optional().describe('分类 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            iteration_id: z.string().optional().describe('迭代 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -391,10 +391,10 @@ export const testTools = [
     },
     {
         name: "tapd_get_test_plan_count",
-        description: "获取测试计划数量",
+        description: "按相同过滤条件返回测试计划数量。要看列表用计划列表查询工具。读操作。返回 {count}。",
         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 安全整数范围会丢精度'),
             name: z.string().optional().describe("测试计划名称"),
             status: z.string().optional().describe("状态"),
             creator: z.string().optional().describe("创建人"),
@@ -411,10 +411,10 @@ export const testTools = [
     // 测试计划详情
     {
         name: "tapd_get_test_plan_details",
-        description: "获取测试计划测试结果详情",
+        description: "查询测试计划内用例的测试结果明细。整体进度统计用执行进度查询工具。读操作；test_plan_id 必填。返回结果明细。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             limit: z.number().optional().describe("返回数量"),
             page: z.number().optional().describe("页码"),
             fields: z.string().optional().describe("返回字段"),
@@ -429,10 +429,10 @@ export const testTools = [
     },
     {
         name: "tapd_get_test_plan_progress",
-        description: "获取测试计划执行进度",
+        description: "查询测试计划执行进度（通过/失败/阻塞统计）。逐用例明细用结果明细查询工具。读操作；test_plan_id 必填。返回进度统计。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -444,9 +444,9 @@ export const testTools = [
     },
     {
         name: "tapd_get_test_plan_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();
@@ -459,11 +459,11 @@ export const testTools = [
     // 测试计划关联
     {
         name: "tapd_get_test_plan_tcases",
-        description: "获取测试计划关联的测试用例",
+        description: "查询测试计划已关联的测试用例。加入用例用计划侧用例关联建立工具。读操作；test_plan_id 必填。返回用例数组。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            tcase_id: z.string().optional().describe('测试用例ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            tcase_id: z.string().optional().describe('测试用例 ID；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             limit: z.number().optional().describe("返回数量"),
             page: z.number().optional().describe("页码"),
             fields: z.string().optional().describe("返回字段"),
@@ -478,10 +478,10 @@ export const testTools = [
     },
     {
         name: "tapd_get_test_plan_relative_stories",
-        description: "获取测试计划关联的需求",
+        description: "查询测试计划已关联的需求。建立关联用计划侧需求关联建立工具。读操作；test_plan_id 必填。返回需求列表。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             limit: z.number().optional().describe("返回数量"),
             page: z.number().optional().describe("页码"),
             fields: z.string().optional().describe("返回字段"),
@@ -496,10 +496,10 @@ export const testTools = [
     },
     {
         name: "tapd_get_test_plan_bugs",
-        description: "获取测试计划关联的缺陷",
+        description: "查询测试计划关联的缺陷。读操作；test_plan_id 必填。返回缺陷列表。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
             limit: z.number().optional().describe("返回数量"),
             page: z.number().optional().describe("页码"),
             fields: z.string().optional().describe("返回字段"),
@@ -514,11 +514,11 @@ export const testTools = [
     },
     {
         name: "tapd_create_story_relation",
-        description: "创建测试计划与需求关联",
+        description: "把需求关联到测试计划。解除用计划侧需求关联解除工具；查询用计划侧关联需求查询工具。写操作；test_plan_id、story_id 必填。返回关联结果。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            story_id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            story_id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -530,11 +530,11 @@ export const testTools = [
     },
     {
         name: "tapd_delete_story_relation",
-        description: "解除测试计划与需求关联",
+        description: "解除测试计划与需求的关联。建立用计划侧需求关联建立工具。写操作；test_plan_id、story_id 必填。返回解除结果。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            story_id: z.string().describe('需求ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            story_id: z.string().describe('需求 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();
@@ -546,11 +546,11 @@ export const testTools = [
     },
     {
         name: "tapd_create_tcase_relation",
-        description: "创建测试计划与测试用例关联",
+        description: "把测试用例关联到测试计划（tcase_id 支持逗号分隔多个）。移出用移出工具。写操作；test_plan_id、tcase_id 必填。返回关联结果。",
         inputSchema: z.object({
-            workspace_id: z.number().optional().describe('项目ID（可省略，使用默认配置）'),
-            test_plan_id: z.string().describe('测试计划ID (必填)；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
-            tcase_id: z.string().describe('测试用例ID (必填)，支持多个ID逗号分隔；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            workspace_id: z.number().optional().describe('项目 ID，可省略（默认取环境变量 TAPD_DEFAULT_WORKSPACE_ID）'),
+            test_plan_id: z.string().describe('测试计划 ID（必填）；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
+            tcase_id: z.string().describe('测试用例 ID（必填），支持多个 ID 逗号分隔；必须以字符串（带引号）传递，禁止传数值，20 位 ID 超出 JS 安全整数范围会丢精度'),
         }),
         handler: async (client, params) => {
             const workspaceId = params.workspace_id ?? TapdClient.getDefaultWorkspaceId();