@testkase/test-management-mcp 2.4.1 → 2.6.0

package/build/index.js

@@ -3,6 +3,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
+import { compact, flattenFolders, pick, shapeList } from "./compact.js";
 const config = {
     apiBaseUrl: (process.env.TESTKASE_API_BASE_URL || "https://api.testkase.com").replace(/\/+$/, ""),
     patToken: process.env.TESTKASE_PAT_TOKEN,
@@ -12,8 +13,8 @@ const config = {
         : undefined,
     appUrl: process.env.TESTKASE_APP_URL?.replace(/\/+$/, ""),
 };
-const VERSION = "2.4.1";
-const REQUEST_TIMEOUT_MS = 60_000;
+const VERSION = "2.5.0";
+const REQUEST_TIMEOUT_MS = Number(process.env.TESTKASE_TIMEOUT_MS) || 60_000;
 // ─── Frontend URL helper ─────────────────────────────────────────────────────
 // Test management lives on its own subdomain
 const KNOWN_APP_HOSTS = {
@@ -88,13 +89,29 @@ async function callApi(method, path, options = {}) {
     }
     const qs = queryParams.toString();
     const url = `${config.apiBaseUrl}/api/v1/${path}${qs ? `?${qs}` : ""}`;
-    const response = await axios({
+    const send = () => axios({
         method,
         url,
         headers: getApiHeaders(),
         timeout: REQUEST_TIMEOUT_MS,
         ...(options.body !== undefined && { data: options.body }),
     });
+    let response;
+    try {
+        response = await send();
+    }
+    catch (error) {
+        // Reads are safe to repeat: retry once on a dropped connection or 502/503/504. Writes and timeouts never retry.
+        const status = axios.isAxiosError(error) ? error.response?.status : undefined;
+        const transient = axios.isAxiosError(error) &&
+            error.code !== "ECONNABORTED" &&
+            error.code !== "ETIMEDOUT" &&
+            (!error.response || [502, 503, 504].includes(status));
+        if (method !== "get" || !transient)
+            throw error;
+        await new Promise((r) => setTimeout(r, 500));
+        response = await send();
+    }
     // Some endpoints report "not found" as HTTP 200 with status "error"
     const data = response.data;
     if (data && typeof data === "object" && data.status === "error") {
@@ -107,6 +124,12 @@ async function callApi(method, path, options = {}) {
 function handleApiError(error) {
     if (axios.isAxiosError(error)) {
         const e = error;
+        if (e.code === "ECONNABORTED" || e.code === "ETIMEDOUT") {
+            const isRead = (e.config?.method ?? "get").toLowerCase() === "get";
+            return new Error(isRead
+                ? `Request timed out after ${REQUEST_TIMEOUT_MS} ms. Try a smaller limit or set TESTKASE_TIMEOUT_MS.`
+                : `Request timed out after ${REQUEST_TIMEOUT_MS} ms. The change may have been applied: check (search/get) before retrying.`);
+        }
         let msg = `API request failed: ${e.message}`;
         if (e.response) {
             msg += `\nStatus: ${e.response.status}`;
@@ -125,11 +148,35 @@ function handleApiError(error) {
     return error;
 }
 // ─── JSON response helper ────────────────────────────────────────────────────
-function jsonResponse(data) {
+// Replies are compact JSON (no indentation, no empty values); verbose returns the raw backend data
+function jsonResponse(data, verbose = false) {
     return {
-        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        content: [{ type: "text", text: JSON.stringify(verbose ? data : compact(data)) }],
     };
 }
+const LIST_KEYS = {
+    testcases: ["id", "title", "priority", "status", "automated"],
+    cycles: ["test_cycle_id", "title", "status", "progress", "execution_summary", "folder_path"],
+    plans: ["test_plan_id", "title", "status", "progress", "test_cycle_count", "testcase_count", "execution_summary", "folder_path"],
+    linkedCases: ["test_case_id", "title", "priority", "execution_status", "assignee=assignee.assignee_name"],
+    projects: ["project_id", "name", "role"],
+};
+// Lists: chosen fields + paging, unless the caller asks for the raw reply
+function listResponse(args, data, keys, urlIdKey) {
+    const verbose = !!p(args, "verbose");
+    return jsonResponse(verbose ? data : shapeList(data, keys, urlIdKey), verbose);
+}
+function memberRow(m) {
+    const name = String(m.name ?? [m.first_name ?? m.firstName, m.last_name ?? m.lastName].filter(Boolean).join(" ")).trim();
+    return { ...pick(m, ["user_id", "id"]), ...(name ? { name } : {}), ...pick(m, ["email", "role"]) };
+}
+const JSON_EXAMPLES = {
+    test_steps: '[{"description":"Open the login page","expected_result":"Form is shown"}]',
+    testcases: '[{"title":"Login works","test_steps":[{"description":"Open the login page"}]}]',
+    results: '[{"testcase_id":"TEST-1","execution_status":"pass"}]',
+    filters: '{"status":["Active"]}',
+    custom_fields: '{"Browser":"Chrome"}',
+};
 function safeJsonParse(raw, fieldName) {
     if (typeof raw !== "string")
         return raw;
@@ -137,9 +184,37 @@ function safeJsonParse(raw, fieldName) {
         return JSON.parse(raw);
     }
     catch {
-        throw new Error(`Invalid JSON in ${fieldName}. Ensure the value is valid JSON.`);
+        const example = JSON_EXAMPLES[fieldName];
+        if (!example)
+            throw new Error(`Invalid JSON in ${fieldName}. Ensure the value is valid JSON.`);
+        const kind = example.startsWith("[") ? "JSON array" : "JSON object";
+        throw new Error(`Invalid JSON in ${fieldName}. Send it as a ${kind} (not inside a string), e.g. ${fieldName}: ${example}`);
     }
 }
+// Small models write "Passed", "FAILED", "not run": map them to the API's values
+const EXECUTION_STATUS = {
+    pass: "pass", passed: "pass", ok: "pass", success: "pass",
+    fail: "fail", failed: "fail", failure: "fail",
+    blocked: "blocked", block: "blocked",
+    not_executed: "not_executed", not_run: "not_executed", notrun: "not_executed", untested: "not_executed",
+    not_tested: "not_executed", unexecuted: "not_executed", pending: "not_executed",
+};
+const PLAN_STATUS = {
+    open: "open", new: "open", not_started: "open", todo: "open",
+    in_progress: "in_progress", inprogress: "in_progress", started: "in_progress", active: "in_progress",
+    completed: "completed", complete: "completed", done: "completed", closed: "completed", finished: "completed",
+};
+const statusKey = (v) => String(v).trim().toLowerCase().replace(/[\s-]+/g, "_");
+function normalizeExecutionStatus(v, where) {
+    const s = EXECUTION_STATUS[statusKey(v)];
+    if (!s)
+        throw new Error(`${where}: execution_status "${v}" is not valid. Use one of: pass, fail, blocked, not_executed`);
+    return s;
+}
+// Unknown values pass through so the API can explain them
+function normalizePlanStatus(v) {
+    return v === undefined || v === null || v === "" ? v : PLAN_STATUS[statusKey(v)] ?? v;
+}
 function validateId(id, fieldName) {
     const str = String(id);
     if (!/^[a-zA-Z0-9_\-]+$/.test(str)) {
@@ -177,6 +252,11 @@ function parseSteps(raw) {
         throw new Error("test_steps must be a JSON array");
     return parsed.map(normalizeStep);
 }
+// Step ids + text in their current order
+async function currentSteps(projectId, testcaseId) {
+    const detail = await callApi("get", `projects/testcases/get-testcase-detail/${projectId}/${testcaseId}`);
+    return (detail?.data?.steps || []).map((st) => pick(st, ["id", "description"]));
+}
 // Steps are added one call each; collect failures instead of aborting
 async function addSteps(projectId, testcaseId, steps) {
     let created = 0;
@@ -212,6 +292,11 @@ function buildFilters(raw, extra = {}) {
     }
     return Object.keys(merged).length ? JSON.stringify(merged) : undefined;
 }
+// create_bulk: these top-level args are defaults for every item
+const BULK_SHARED_FIELDS = [
+    "folder_id", "folderId", "priority", "status", "automated", "platform", "labels", "features", "environment",
+    "owner_id", "ownerId", "precondition", "custom_fields", "customFields",
+];
 // Builds the create/bulk-create payload from tool args (shared by both actions)
 async function buildTestcasePayload(projectId, tc) {
     const data = { title: tc.title ?? tc.name };
@@ -256,12 +341,9 @@ async function buildTestcasePayload(projectId, tc) {
     return data;
 }
 function jsonResponseWithHints(data, hints) {
-    const json = JSON.stringify(data, null, 2);
-    const hintsBlock = hints.length > 0
-        ? `\n\n---\nHINTS:\n${hints.map((h) => `- ${h}`).join("\n")}`
-        : "";
+    const hintsBlock = hints.length > 0 ? `\nHINTS: ${hints.join(" | ")}` : "";
     return {
-        content: [{ type: "text", text: json + hintsBlock }],
+        content: [{ type: "text", text: JSON.stringify(compact(data)) + hintsBlock }],
     };
 }
 // ─── Error enrichment ───────────────────────────────────────────────────────
@@ -339,331 +421,235 @@ function requireArg(args, name, aliases = []) {
     return value;
 }
 // ═══════════════════════════════════════════════════════════════════════════════
+// REPORT TYPE → ENDPOINT MAPPING
+// ═══════════════════════════════════════════════════════════════════════════════
+const REPORT_TYPE_MAP = {
+    // Execution
+    execution_summary: "execution/summary",
+    execution_by_cycle: "execution/by-cycle",
+    execution_by_tester: "execution/by-tester",
+    execution_by_priority: "execution/by-priority",
+    execution_by_environment: "execution/by-environment",
+    execution_by_folder: "execution/by-folder",
+    // Coverage
+    requirement_coverage: "coverage/requirement-coverage",
+    traceability_matrix: "coverage/traceability-matrix",
+    failed_requirements: "coverage/failed-requirements",
+    uncovered_requirements: "coverage/uncovered-requirements",
+    testcase_coverage: "coverage/testcase-coverage",
+    unlinked_testcases: "coverage/unlinked-testcases",
+    // Defects
+    defects_by_folder: "defects/by-folder",
+    // Team
+    tester_workload: "team/tester-workload",
+    testcase_distribution: "team/testcase-distribution",
+    // Trends
+    execution_trend: "trends/execution-trend",
+    execution_burnup: "trends/execution-burnup",
+    execution_burndown: "trends/execution-burndown",
+    test_creation: "trends/test-creation",
+    cycle_comparison: "trends/cycle-comparison",
+    scorecard_by_folder: "trends/scorecard-by-folder",
+    scorecard_by_tester: "trends/scorecard-by-tester",
+    created_vs_executed: "trends/created-vs-executed",
+    execution_by_automation: "trends/execution-by-automation",
+    defects_by_cycle: "trends/defects-by-cycle",
+    defects_by_tester: "trends/defects-by-tester",
+    requirement_coverage_trend: "trends/requirement-coverage-trend",
+    // Insights (computed from project data, no AI credits)
+    flaky_tests: "ai/flaky-tests",
+    release_readiness: "ai/release-readiness",
+    risk_heatmap_folder: "ai/risk-heatmap-folder",
+    risk_heatmap_feature: "ai/risk-heatmap-feature",
+    testcase_quality: "ai/testcase-quality",
+    predictive_failure: "ai/predictive-failure",
+    smart_prioritization: "ai/smart-prioritization",
+    tester_effectiveness: "ai/tester-effectiveness",
+    stale_tests: "ai/stale-tests",
+    defect_hotspots: "ai/defect-hotspots",
+    cycle_health: "ai/cycle-health",
+    suite_optimization: "ai/suite-optimization",
+    requirement_risk_matrix: "ai/requirement-risk-matrix",
+    execution_velocity: "ai/execution-velocity",
+    project_health: "ai/project-health",
+};
+// ═══════════════════════════════════════════════════════════════════════════════
 // TOOL DEFINITIONS (11 tools)
+// Kept short on purpose: every client sends these on every turn. * = required.
 // ═══════════════════════════════════════════════════════════════════════════════
+const S = { type: "string" };
+const N = { type: "number" };
+const VERBOSE = { type: "boolean" };
+const STATUS = { type: "string", enum: ["open", "in_progress", "completed"] };
+const SECTION = { type: "string", enum: ["TESTCASE", "TEST_CYCLE", "TEST_PLAN"] };
+const CSV = S;
+const PROJECT_VALUE = S;
 const LIST_PROJECTS_TOOL = {
     name: "list_projects",
-    description: "List all projects the authenticated user has access to. " +
-        "Use this first to find a projectId, then pass it to other tools.",
+    description: "Projects you can access. Start here to get a projectId.",
     annotations: { readOnlyHint: true },
-    inputSchema: {
-        type: "object",
-        properties: {
-            page: { type: "number", description: "Page number (default: 1)" },
-            limit: { type: "number", description: "Items per page (default: 12)" },
-        },
-        required: [],
-    },
+    inputSchema: { type: "object", properties: { page: N, limit: N, verbose: VERBOSE }, required: [] },
 };
 const GET_PROJECT_STRUCTURE_TOOL = {
     name: "get_project_structure",
-    description: "Get the structure of a project: folders, labels, team members, and field options (allowed values for priority, status, etc.). " +
-        "IMPORTANT: Call this before create/update to discover allowed field values, which are project-specific.",
+    description: "Folders, labels, members, field_options. Call before create/update: priority, status etc. accept only these values (any case).",
     annotations: { readOnlyHint: true },
     inputSchema: {
         type: "object",
         properties: {
-            projectId: { type: "string", description: "Project ID (e.g. PRJ-1001)" },
-            section: {
-                type: "string",
-                enum: ["TESTCASE", "TEST_CYCLE", "TEST_PLAN"],
-                description: "Folder section (default: TESTCASE)",
-            },
-            include: {
-                type: "string",
-                description: "Comma-separated list of what to include: folders,labels,members,field_options (default: all)",
-            },
+            projectId: S,
+            section: SECTION,
+            include: { type: "string", description: "CSV of folders,labels,members,field_options (default all)" },
+            verbose: VERBOSE,
         },
         required: ["projectId"],
     },
 };
 const SEARCH_TESTCASES_TOOL = {
     name: "search_testcases",
-    description: "Search and list test cases in a project. Supports text search, folder filter, filters, sorting, and pagination.",
+    description: "Search/list test cases.",
     annotations: { readOnlyHint: true },
     inputSchema: {
         type: "object",
         properties: {
-            projectId: { type: "string", description: "Project ID" },
-            search: { type: "string", description: "Search text (ID, title, summary, field values)" },
-            folder_id: {
-                type: "number",
-                description: "Only test cases in this folder (sub-folders included). Use 0 for test cases with no folder.",
-            },
-            filters: {
-                type: "string",
-                description: 'JSON object of filters; every value is a list. Keys are field names (use the field_options names). ' +
-                    'Example: {"status":["Active"],"priority":["High","Critical"]}. Also supports "exclude_status".',
-            },
-            page: { type: "number", description: "Page number (default: 1)" },
-            limit: { type: "number", description: "Items per page (default: 20, max: 100)" },
-            sortBy: { type: "string", description: "Field to sort by (e.g. created_at, title)" },
-            sortOrder: { type: "string", enum: ["asc", "desc"], description: "Sort direction" },
+            projectId: S,
+            search: S,
+            folder_id: { type: "number", description: "includes sub-folders; 0 = no folder" },
+            filters: { type: "object", description: 'values are lists: {"status":["Active"]}; also exclude_status' },
+            page: N,
+            limit: { type: "number", description: "max 100" },
+            sortBy: S,
+            sortOrder: { type: "string", enum: ["asc", "desc"] },
+            verbose: VERBOSE,
         },
         required: ["projectId"],
     },
 };
 const GET_TESTCASE_TOOL = {
     name: "get_testcase",
-    description: "Get full details of a single test case including test steps (with step ids) and attachments.",
+    description: "One test case + steps + attachments (view/download).",
     annotations: { readOnlyHint: true },
-    inputSchema: {
-        type: "object",
-        properties: {
-            projectId: { type: "string", description: "Project ID" },
-            testcaseId: { type: "string", description: "Test case ID (e.g. TEST-123)" },
-        },
-        required: ["projectId", "testcaseId"],
-    },
+    inputSchema: { type: "object", properties: { projectId: S, testcaseId: S, verbose: VERBOSE }, required: ["projectId", "testcaseId"] },
 };
 const TESTCASE_FIELDS = "title, summary, precondition, priority, status, automated, test_data, expected_result, labels, features, platform, environment, custom_fields, owner_id, folder_id";
 const MANAGE_TESTCASE_TOOL = {
     name: "manage_testcase",
-    description: "IMPORTANT: Before creating/updating, call get_project_structure(projectId) to discover folder IDs and allowed field values.\n\n" +
-        "Create, update or delete test cases and their test steps.\n\n" +
-        "ACTIONS:\n" +
-        "  create        - Create a single test case. Params: title (required), test_steps, and any of: " + TESTCASE_FIELDS + "\n" +
-        "  create_bulk   - Create up to 100 test cases in one go. Params: testcases (JSON array; each item takes the same fields as create, including test_steps)\n" +
-        "  update        - Update one field for test case(s). Params: ids, field, value (all required)\n" +
-        "  delete        - PERMANENTLY delete test case(s) with their steps, history and links. Params: ids (required)\n" +
-        "  add_steps     - Append steps to a test case. Params: testcaseId, test_steps\n" +
-        "  update_step   - Change one step. Params: testcaseId, step_id, and description/test_data/expected_result\n" +
-        "  delete_steps  - Delete steps. Params: testcaseId, step_ids (comma-separated)\n" +
-        "  reorder_steps - Set the step order. Params: testcaseId, step_ids (all step ids, in the new order)\n" +
-        "Step ids come from get_testcase.\n\n" +
-        "VALID UPDATE FIELDS: " + TESTCASE_FIELDS + "\n\n" +
-        "EXAMPLES:\n" +
-        "  Create:  { action: 'create', title: 'Verify login', test_steps: '[{\"description\":\"Open login page\",\"expected_result\":\"Form shown\"}]' }\n" +
-        "  Update:  { action: 'update', ids: 'TEST-1', field: 'priority', value: '<value from get_project_structure>' }\n" +
-        "  Delete:  { action: 'delete', ids: 'TEST-1,TEST-2' }",
+    description: "* = required, ids are CSV. create(title*) | create_bulk(testcases*, max 100) | update(ids*, field*, value*): one field | " +
+        "delete(ids*): permanent | add_steps(testcaseId*, test_steps*) | update_step(testcaseId*, step_id*) | delete_steps(testcaseId*, step_ids*) | " +
+        "reorder_steps(testcaseId*, step_ids*: all, new order)",
     annotations: { destructiveHint: true },
     inputSchema: {
         type: "object",
         properties: {
-            projectId: { type: "string", description: "Project ID" },
-            action: {
-                type: "string",
-                enum: ["create", "create_bulk", "update", "delete", "add_steps", "update_step", "delete_steps", "reorder_steps"],
-                description: "Action to perform",
-            },
-            // create params
-            title: { type: "string", description: "[create] Test case title" },
-            summary: { type: "string", description: "[create] Description/summary" },
-            priority: {
-                type: "string",
-                description: "[create] Priority. Values are project-specific — call get_project_structure(projectId, include='field_options') first to discover allowed values.",
-            },
-            folder_id: { type: "number", description: "[create] Folder ID to place the test case in" },
-            labels: {
-                type: "string",
-                description: "[create] Comma-separated label names",
-            },
-            test_steps: {
-                type: "string",
-                description: '[create/add_steps] JSON array of test steps: [{"description":"...","test_data":"...","expected_result":"..."}]. Every step needs a description.',
-            },
-            precondition: { type: "string", description: "[create] Preconditions for the test case" },
-            status: {
-                type: "string",
-                description: "[create] Status. Values are project-specific — call get_project_structure(projectId, include='field_options') first.",
-            },
-            automated: {
-                type: "string",
-                description: "[create] Automation status. Values are project-specific — call get_project_structure(projectId, include='field_options') first.",
-            },
-            test_data: { type: "string", description: "[create/update_step] Test data" },
-            expected_result: { type: "string", description: "[create/update_step] Expected result" },
-            platform: {
-                type: "string",
-                description: "[create] Platform. Values are project-specific — call get_project_structure(projectId, include='field_options') first.",
-            },
-            environment: { type: "string", description: "[create] Comma-separated environment values" },
-            features: { type: "string", description: "[create] Comma-separated feature/component names" },
-            owner_id: { type: "string", description: "[create] Owner user ID (a project member)" },
-            custom_fields: {
-                type: "string",
-                description: '[create] JSON object of custom field values (e.g. {"custom1": "value", "custom2": ["val1","val2"]})',
-            },
-            // create_bulk params
-            testcases: {
-                type: "string",
-                description: "[create_bulk] JSON array of test cases. Each item takes the create fields, e.g. " +
-                    '[{"title":"...","folder_id":12,"priority":"High","test_steps":[{"description":"...","expected_result":"..."}]}]',
-            },
-            // update/delete params
-            ids: {
-                type: "string",
-                description: "[update/delete] Test case IDs, comma-separated (e.g. 'TEST-1' or 'TEST-1,TEST-2')",
-            },
-            field: {
-                type: "string",
-                enum: TESTCASE_FIELDS.split(", "),
-                description: "[update] Field to update. For priority/status/automated/platform/environment, call get_project_structure(include='field_options') to get allowed values.",
-            },
-            value: { type: "string", description: "[update] New value. String for most fields. For labels/features/environment: comma-separated. For custom_fields: JSON object (e.g. {\"fieldName\": \"value\"})" },
-            // step params
-            testcaseId: { type: "string", description: "[add_steps/update_step/delete_steps/reorder_steps] Test case ID (e.g. TEST-123)" },
-            step_id: { type: "number", description: "[update_step] Step ID to change" },
-            description: { type: "string", description: "[update_step] Step description" },
-            step_ids: { type: "string", description: "[delete_steps/reorder_steps] Comma-separated step IDs" },
+            projectId: S,
+            action: { type: "string", enum: ["create", "create_bulk", "update", "delete", "add_steps", "update_step", "delete_steps", "reorder_steps"] },
+            title: S,
+            summary: S,
+            precondition: S,
+            priority: PROJECT_VALUE,
+            status: PROJECT_VALUE,
+            automated: PROJECT_VALUE,
+            platform: PROJECT_VALUE,
+            folder_id: N,
+            labels: CSV,
+            features: CSV,
+            environment: CSV,
+            test_data: S,
+            expected_result: S,
+            owner_id: S,
+            custom_fields: { type: "object" },
+            test_steps: { type: "array", items: { type: "object", properties: { description: S, test_data: S, expected_result: S } } },
+            testcases: { type: "array", items: { type: "object" }, description: "top-level fields apply to all" },
+            ids: CSV,
+            field: { type: "string", enum: TESTCASE_FIELDS.split(", ") },
+            value: { type: "string", description: "CSV for list fields, JSON for custom_fields" },
+            testcaseId: S,
+            step_id: N,
+            description: S,
+            step_ids: CSV,
         },
         required: ["projectId", "action"],
     },
 };
 const MANAGE_FOLDER_TOOL = {
     name: "manage_folder",
-    description: "Create, rename, move, or delete folders. Works across all sections (TESTCASE, TEST_CYCLE, TEST_PLAN).\n\n" +
-        "ACTIONS:\n" +
-        "  create  - Create a folder. Params: name (required), section, parentId\n" +
-        "  rename  - Rename a folder. Params: folderId (required), name (required)\n" +
-        "  move    - Move a folder. Params: folderId (required), parentId (omit or null for root)\n" +
-        "  delete  - PERMANENTLY delete a folder, all its sub-folders AND every test case / cycle / plan inside them. " +
-        "Only owners and project admins can do this. Confirm with the user first. Params: folderId (required)",
+    description: "create(name*, parentId) | rename(folderId*, name*) | move(folderId*, parentId: omit = root) | " +
+        "delete(folderId*): deletes its contents too; confirm with the user",
     annotations: { destructiveHint: true },
     inputSchema: {
         type: "object",
         properties: {
-            projectId: { type: "string", description: "Project ID" },
-            action: {
-                type: "string",
-                enum: ["create", "rename", "move", "delete"],
-                description: "Action to perform",
-            },
-            section: {
-                type: "string",
-                enum: ["TESTCASE", "TEST_CYCLE", "TEST_PLAN"],
-                description: "Folder section (default: TESTCASE)",
-            },
-            name: { type: "string", description: "[create/rename] Folder name (max 50 chars)" },
-            folderId: {
-                type: "number",
-                description: "[rename/move/delete] ID of the folder to modify",
-            },
-            parentId: {
-                type: "number",
-                description: "[create] Parent folder ID for subfolder. [move] New parent ID (null for root).",
-            },
+            projectId: S,
+            action: { type: "string", enum: ["create", "rename", "move", "delete"] },
+            section: SECTION,
+            name: { type: "string", description: "max 50 chars" },
+            folderId: N,
+            parentId: N,
         },
         required: ["projectId", "action"],
     },
 };
 const SEARCH_TEST_CYCLES_TOOL = {
     name: "search_test_cycles",
-    description: "List and search test cycles in a project with execution progress.",
+    description: "Search/list test cycles with progress.",
     annotations: { readOnlyHint: true },
     inputSchema: {
         type: "object",
-        properties: {
-            projectId: { type: "string", description: "Project ID" },
-            search: { type: "string", description: "Search by title" },
-            folderId: { type: "number", description: "Filter by folder ID" },
-            status: { type: "string", enum: ["open", "in_progress", "completed"], description: "Filter by status" },
-            page: { type: "number", description: "Page number (default: 1)" },
-            limit: { type: "number", description: "Items per page (default: 20, max: 100)" },
-        },
+        properties: { projectId: S, search: S, folderId: N, status: STATUS, page: N, limit: N, verbose: VERBOSE },
         required: ["projectId"],
     },
 };
 const MANAGE_TEST_CYCLE_TOOL = {
     name: "manage_test_cycle",
-    description: "Manage test cycles: create, update, delete, get details, list/link/unlink/assign test cases.\n\n" +
-        "ACTIONS:\n" +
-        "  create            - Create a cycle. Params: title (required), summary, status, planned_start_date, planned_end_date, folder_id\n" +
-        "  update            - Update a cycle. Params: cycleId (required), plus fields to change (title, summary, status, dates, folder_id)\n" +
-        "  delete            - Delete cycle(s). Params: ids (required, comma-separated)\n" +
-        "  get_details       - Get cycle details. Params: cycleId (required)\n" +
-        "  get_testcases     - List test cases in cycle. Params: cycleId (required), search, page, limit\n" +
-        "  link_testcases    - Link test cases to cycle. Params: cycleId (required), testcase_ids (required, comma-separated)\n" +
-        "  unlink_testcases  - Unlink test cases from cycle. Params: cycleId (required), testcase_ids (required, comma-separated)\n" +
-        "  assign_testcases  - Assign test cases to user. Params: cycleId (required), testcase_ids (required), assignee_id (required)\n\n" +
-        "VALID STATUSES: open, in_progress, completed",
+    description: "create(title*, status, dates, folder_id) | update(cycleId*) | delete(ids*) | get_details(cycleId*) | get_testcases(cycleId*) | " +
+        "link_testcases/unlink_testcases(cycleId*, testcase_ids*) | assign_testcases(cycleId*, testcase_ids*, assignee_id*: member user_id). Dates YYYY-MM-DD.",
     annotations: { destructiveHint: true },
     inputSchema: {
         type: "object",
         properties: {
-            projectId: { type: "string", description: "Project ID" },
+            projectId: S,
             action: {
                 type: "string",
-                enum: [
-                    "create",
-                    "update",
-                    "delete",
-                    "get_details",
-                    "get_testcases",
-                    "link_testcases",
-                    "unlink_testcases",
-                    "assign_testcases",
-                ],
-                description: "Action to perform",
-            },
-            // Identifiers
-            cycleId: {
-                type: "string",
-                description: "Test cycle ID (e.g. TCYCLE-1). Required for update/delete/get_details/get_testcases/link/unlink/assign.",
-            },
-            // create/update fields
-            title: { type: "string", description: "[create/update] Cycle title" },
-            summary: { type: "string", description: "[create/update] Description" },
-            status: {
-                type: "string",
-                enum: ["open", "in_progress", "completed"],
-                description: "[create/update] Status",
-            },
-            planned_start_date: {
-                type: "string",
-                description: "[create/update] Start date (YYYY-MM-DD)",
-            },
-            planned_end_date: {
-                type: "string",
-                description: "[create/update] End date (YYYY-MM-DD)",
-            },
-            folder_id: {
-                type: "number",
-                description: "[create/update] Folder ID",
-            },
-            // delete
-            ids: {
-                type: "string",
-                description: "[delete] Comma-separated cycle IDs to delete",
+                enum: ["create", "update", "delete", "get_details", "get_testcases", "link_testcases", "unlink_testcases", "assign_testcases"],
             },
-            // link/unlink/assign
-            testcase_ids: {
-                type: "string",
-                description: "[link_testcases/unlink_testcases/assign_testcases] Comma-separated test case IDs",
-            },
-            assignee_id: {
-                type: "number",
-                description: "[assign_testcases] User ID to assign",
-            },
-            // get_testcases params
-            search: { type: "string", description: "[get_testcases] Search text" },
-            page: { type: "number", description: "[get_testcases] Page number" },
-            limit: { type: "number", description: "[get_testcases] Items per page" },
+            cycleId: S,
+            title: S,
+            summary: S,
+            status: STATUS,
+            planned_start_date: S,
+            planned_end_date: S,
+            folder_id: N,
+            ids: CSV,
+            testcase_ids: CSV,
+            assignee_id: N,
+            search: S,
+            page: N,
+            limit: N,
+            verbose: VERBOSE,
         },
         required: ["projectId", "action"],
     },
 };
 const EXECUTE_TESTS_TOOL = {
     name: "execute_tests",
-    description: "Record test execution results for test cases in a test cycle. " +
-        "Pass a single result or an array of results. " +
-        "Valid execution statuses: pass, fail, blocked, not_executed. " +
-        "The test cases must already be linked to the cycle (manage_test_cycle link_testcases).",
+    description: "Record results for test cases already linked to the cycle.",
     inputSchema: {
         type: "object",
         properties: {
-            projectId: { type: "string", description: "Project ID" },
-            cycleId: { type: "string", description: "Test cycle ID (e.g. TCYCLE-1)" },
+            projectId: S,
+            cycleId: S,
             results: {
-                type: "string",
-                description: 'JSON array of results: [{"testcase_id":"TEST-1","execution_status":"pass","actual_result":"Worked","environment":"staging"}]. ' +
-                    "Each object must have testcase_id and execution_status. actual_result and environment are optional.",
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: { testcase_id: S, execution_status: { type: "string", enum: ["pass", "fail", "blocked", "not_executed"] }, actual_result: S },
+                    required: ["testcase_id", "execution_status"],
+                },
             },
             mode: {
                 type: "string",
                 enum: ["manual", "automation"],
-                description: "manual (default): each result is recorded like a tester setting it in the app — the new status replaces the old one. " +
-                    "automation: recorded as a CI/automation run, where a failure from any earlier automation run keeps the case failed. Use only for CI results.",
+                description: "automation = CI run: an earlier CI fail keeps it failed",
             },
         },
         required: ["projectId", "cycleId", "results"],
@@ -671,177 +657,56 @@ const EXECUTE_TESTS_TOOL = {
 };
 const MANAGE_TEST_PLAN_TOOL = {
     name: "manage_test_plan",
-    description: "Manage test plans: create, update, delete, list, get details, link/unlink cycles, get cycles, get test cases.\n\n" +
-        "ACTIONS:\n" +
-        "  create         - Create a plan. Params: title (required), summary, status, planned_start_date, planned_end_date, folder_id\n" +
-        "  update         - Update a plan. Params: planId (required), plus fields to change (title, summary, status, dates, folder_id)\n" +
-        "  delete         - Delete plan(s). Params: ids (required, comma-separated)\n" +
-        "  list           - List all plans. Params: search, page, limit\n" +
-        "  get_details    - Get plan details. Params: planId (required)\n" +
-        "  link_cycles    - Link cycles to plan. Params: planId (required), cycle_ids (required, comma-separated)\n" +
-        "  unlink_cycles  - Unlink cycles from plan. Params: planId (required), cycle_ids (required, comma-separated)\n" +
-        "  get_cycles     - List cycles in plan. Params: planId (required), search, page, limit\n" +
-        "  get_testcases  - List test cases in plan. Params: planId (required), search, page, limit\n\n" +
-        "VALID STATUSES: open, in_progress, completed",
+    description: "create(title*, status, dates, folder_id) | update(planId*) | delete(ids*) | list | get_details(planId*) | link_cycles/unlink_cycles(planId*, cycle_ids*) | " +
+        "get_cycles/get_testcases(planId*). Dates YYYY-MM-DD.",
     annotations: { destructiveHint: true },
     inputSchema: {
         type: "object",
         properties: {
-            projectId: { type: "string", description: "Project ID" },
+            projectId: S,
             action: {
                 type: "string",
-                enum: [
-                    "create",
-                    "update",
-                    "delete",
-                    "list",
-                    "get_details",
-                    "link_cycles",
-                    "unlink_cycles",
-                    "get_cycles",
-                    "get_testcases",
-                ],
-                description: "Action to perform",
-            },
-            // Identifier
-            planId: {
-                type: "string",
-                description: "Test plan ID (e.g. TPLAN-1). Required for update/delete/get_details/link_cycles/unlink_cycles/get_cycles/get_testcases.",
+                enum: ["create", "update", "delete", "list", "get_details", "link_cycles", "unlink_cycles", "get_cycles", "get_testcases"],
             },
-            // create/update fields
-            title: { type: "string", description: "[create/update] Plan title" },
-            summary: { type: "string", description: "[create/update] Description" },
-            status: { type: "string", enum: ["open", "in_progress", "completed"], description: "[create/update] Status" },
-            planned_start_date: {
-                type: "string",
-                description: "[create/update] Start date (YYYY-MM-DD)",
-            },
-            planned_end_date: {
-                type: "string",
-                description: "[create/update] End date (YYYY-MM-DD)",
-            },
-            folder_id: { type: "number", description: "[create/update] Folder ID" },
-            // delete
-            ids: {
-                type: "string",
-                description: "[delete] Comma-separated plan IDs to delete",
-            },
-            // link/unlink cycles
-            cycle_ids: {
-                type: "string",
-                description: "[link_cycles/unlink_cycles] Comma-separated test cycle IDs",
-            },
-            // list/get_cycles/get_testcases pagination
-            search: { type: "string", description: "[list/get_cycles/get_testcases] Search text" },
-            page: { type: "number", description: "[list/get_cycles/get_testcases] Page number" },
-            limit: { type: "number", description: "[list/get_cycles/get_testcases] Items per page" },
+            planId: S,
+            title: S,
+            summary: S,
+            status: STATUS,
+            planned_start_date: S,
+            planned_end_date: S,
+            folder_id: N,
+            ids: CSV,
+            cycle_ids: CSV,
+            search: S,
+            page: N,
+            limit: N,
+            verbose: VERBOSE,
         },
         required: ["projectId", "action"],
     },
 };
 const GET_REPORT_TOOL = {
     name: "get_report",
-    description: "Get reports and analytics for a project. Covers execution, coverage, trends, team, defects, and insights " +
-        "(the insight reports are computed from your data; they do not use AI credits). " +
-        "Available report types: execution_summary, execution_by_cycle, execution_by_tester, execution_by_priority, " +
-        "execution_by_environment, execution_by_folder, requirement_coverage, traceability_matrix, " +
-        "failed_requirements, uncovered_requirements, testcase_coverage, unlinked_testcases, " +
-        "defects_by_folder, tester_workload, testcase_distribution, " +
-        "execution_trend, execution_burnup, execution_burndown, test_creation, cycle_comparison, " +
-        "scorecard_by_folder, scorecard_by_tester, created_vs_executed, execution_by_automation, " +
-        "defects_by_cycle, defects_by_tester, requirement_coverage_trend, " +
-        "flaky_tests, release_readiness, risk_heatmap_folder, risk_heatmap_feature, " +
-        "testcase_quality, predictive_failure, smart_prioritization, tester_effectiveness, " +
-        "stale_tests, defect_hotspots, cycle_health, suite_optimization, " +
-        "requirement_risk_matrix, execution_velocity, project_health.",
+    description: "Project reports (insights use no AI credits).",
     annotations: { readOnlyHint: true },
     inputSchema: {
         type: "object",
         properties: {
-            projectId: { type: "string", description: "Project ID" },
-            report_type: {
-                type: "string",
-                description: "Report type (see description for full list)",
-            },
-            test_cycle_id: {
-                type: "string",
-                description: "Only this test cycle (one ID, e.g. TCYCLE-3)",
-            },
-            test_plan_id: {
-                type: "string",
-                description: "Only this test plan (one ID, e.g. TPLAN-2)",
-            },
-            folder_id: { type: "number", description: "Only this folder" },
-            startDate: { type: "string", description: "Start date filter (YYYY-MM-DD)" },
-            endDate: { type: "string", description: "End date filter (YYYY-MM-DD)" },
-            granularity: {
-                type: "string",
-                enum: ["day", "week", "month"],
-                description: "Granularity for trend reports",
-            },
-            // cycle_comparison specific
-            cycle_ids: {
-                type: "string",
-                description: "[cycle_comparison] Comma-separated cycle IDs to compare",
-            },
+            projectId: S,
+            report_type: { type: "string", enum: Object.keys(REPORT_TYPE_MAP) },
+            test_cycle_id: { type: "string", description: "one id" },
+            test_plan_id: { type: "string", description: "one id" },
+            folder_id: N,
+            startDate: { type: "string", description: "YYYY-MM-DD" },
+            endDate: { type: "string", description: "YYYY-MM-DD, inclusive" },
+            granularity: { type: "string", enum: ["day", "week", "month"] },
+            cycle_ids: { type: "string", description: "cycle_comparison" },
+            verbose: VERBOSE,
         },
         required: ["projectId", "report_type"],
     },
 };
 // ═══════════════════════════════════════════════════════════════════════════════
-// REPORT TYPE → ENDPOINT MAPPING
-// ═══════════════════════════════════════════════════════════════════════════════
-const REPORT_TYPE_MAP = {
-    // Execution
-    execution_summary: "execution/summary",
-    execution_by_cycle: "execution/by-cycle",
-    execution_by_tester: "execution/by-tester",
-    execution_by_priority: "execution/by-priority",
-    execution_by_environment: "execution/by-environment",
-    execution_by_folder: "execution/by-folder",
-    // Coverage
-    requirement_coverage: "coverage/requirement-coverage",
-    traceability_matrix: "coverage/traceability-matrix",
-    failed_requirements: "coverage/failed-requirements",
-    uncovered_requirements: "coverage/uncovered-requirements",
-    testcase_coverage: "coverage/testcase-coverage",
-    unlinked_testcases: "coverage/unlinked-testcases",
-    // Defects
-    defects_by_folder: "defects/by-folder",
-    // Team
-    tester_workload: "team/tester-workload",
-    testcase_distribution: "team/testcase-distribution",
-    // Trends
-    execution_trend: "trends/execution-trend",
-    execution_burnup: "trends/execution-burnup",
-    execution_burndown: "trends/execution-burndown",
-    test_creation: "trends/test-creation",
-    cycle_comparison: "trends/cycle-comparison",
-    scorecard_by_folder: "trends/scorecard-by-folder",
-    scorecard_by_tester: "trends/scorecard-by-tester",
-    created_vs_executed: "trends/created-vs-executed",
-    execution_by_automation: "trends/execution-by-automation",
-    defects_by_cycle: "trends/defects-by-cycle",
-    defects_by_tester: "trends/defects-by-tester",
-    requirement_coverage_trend: "trends/requirement-coverage-trend",
-    // AI Insights
-    flaky_tests: "ai/flaky-tests",
-    release_readiness: "ai/release-readiness",
-    risk_heatmap_folder: "ai/risk-heatmap-folder",
-    risk_heatmap_feature: "ai/risk-heatmap-feature",
-    testcase_quality: "ai/testcase-quality",
-    predictive_failure: "ai/predictive-failure",
-    smart_prioritization: "ai/smart-prioritization",
-    tester_effectiveness: "ai/tester-effectiveness",
-    stale_tests: "ai/stale-tests",
-    defect_hotspots: "ai/defect-hotspots",
-    cycle_health: "ai/cycle-health",
-    suite_optimization: "ai/suite-optimization",
-    requirement_risk_matrix: "ai/requirement-risk-matrix",
-    execution_velocity: "ai/execution-velocity",
-    project_health: "ai/project-health",
-};
-// ═══════════════════════════════════════════════════════════════════════════════
 // TOOL HANDLERS
 // ═══════════════════════════════════════════════════════════════════════════════
 // 1. list_projects
@@ -852,9 +717,7 @@ async function handleListProjects(args) {
             limit: p(args, "limit"),
         },
     });
-    return jsonResponseWithHints(data, [
-        "Next: call get_project_structure(projectId) to see folders, labels, and allowed field values.",
-    ]);
+    return listResponse(args, data, LIST_KEYS.projects);
 }
 // 2. get_project_structure
 async function handleGetProjectStructure(args) {
@@ -891,9 +754,34 @@ async function handleGetProjectStructure(args) {
         }));
     }
     await Promise.all(promises);
-    return jsonResponseWithHints(result, [
-        "Use the field_options values above when creating/updating test cases.",
-    ]);
+    if (p(args, "verbose"))
+        return jsonResponse(result, true);
+    const unwrap = (d) => (d && typeof d === "object" && !Array.isArray(d) && "data" in d ? d.data : d);
+    const shaped = {};
+    if (result.folders) {
+        const f = unwrap(result.folders);
+        shaped.folders = flattenFolders(Array.isArray(f) ? f : f?.folders ?? []);
+    }
+    if (result.labels) {
+        const l = unwrap(result.labels);
+        shaped.labels = (Array.isArray(l) ? l : []).map((x) => x?.labels ?? x?.name ?? x);
+    }
+    if (result.members) {
+        const m = unwrap(result.members);
+        shaped.members = (Array.isArray(m) ? m : m?.team_members ?? m?.members ?? []).map(memberRow);
+    }
+    if (result.field_options) {
+        shaped.field_options = {};
+        for (const f of Array.isArray(result.field_options) ? result.field_options : []) {
+            // List fields: allowed values. Custom free-text fields: their type, so the AI knows the custom_fields name.
+            if (Array.isArray(f?.values) && f.values.length)
+                shaped.field_options[f.fieldName] = f.values;
+            else if (f?.isSystem === false)
+                shaped.field_options[f.fieldName] = f.fieldType;
+        }
+    }
+    // Not compacted: an empty section must read as "none" (folders: []), not vanish
+    return { content: [{ type: "text", text: JSON.stringify(shaped) }] };
 }
 // 3. search_testcases
 async function handleSearchTestcases(args) {
@@ -925,7 +813,22 @@ async function handleSearchTestcases(args) {
                 tc.url = `${baseUrl}/${projectId}/testcases/${tc.id}`;
         });
     }
-    return jsonResponse(data);
+    return listResponse(args, data, LIST_KEYS.testcases, "id");
+}
+// Keep the useful, shareable fields; drop internal ones (s3_path, uploaded_by, status)
+function shapeAttachments(list) {
+    return (Array.isArray(list) ? list : []).map((a) => {
+        const s3 = typeof a?.s3_path === "string" ? a.s3_path : "";
+        const filename = (s3 ? s3.split("/").pop() : undefined) || a?.filename || a?.name;
+        return {
+            attachment_id: a?.attachment_id ?? a?.id,
+            filename,
+            size: a?.size,
+            uploaded_at: a?.uploaded_at,
+            viewUrl: a?.viewUrl,
+            downloadUrl: a?.downloadUrl,
+        };
+    });
 }
 // 4. get_testcase
 async function handleGetTestcase(args) {
@@ -940,8 +843,22 @@ async function handleGetTestcase(args) {
     const data = await callApi("get", `projects/testcases/get-testcase-detail/${projectId}/${testcaseId}`);
     if (data?.data?.testcase) {
         data.data.testcase.url = `${getFrontendBaseUrl()}/${projectId}/testcases/${testcaseId}`;
+        // Attachments live on a separate endpoint; fold them in so the agent gets shareable
+        // presigned links (view/download) without the test-case read ever failing on their account.
+        try {
+            const orgId = await getOrganizationId();
+            const att = await callApi("get", `attachments/testcase/${orgId}/${projectId}`, {
+                query: { target_id: testcaseId },
+            });
+            data.data.testcase.attachments = shapeAttachments(att?.attachments ?? att?.data?.attachments);
+        }
+        catch {
+            data.data.testcase.attachments = [];
+            data.data.testcase.attachments_note =
+                "Could not load attachments for this test case (the case itself loaded fine). Re-run get_testcase to retry.";
+        }
     }
-    return jsonResponse(data);
+    return jsonResponse(data, !!p(args, "verbose"));
 }
 // 5. manage_testcase
 async function handleManageTestcase(args) {
@@ -963,9 +880,7 @@ async function handleManageTestcase(args) {
             const testcaseData = await buildTestcasePayload(projectId, { ...args, title });
             const createResult = await callApi("post", `projects/testcases/create-testcase/${projectId}`, { body: testcaseData });
             const tcId = createResult?.testcaseId || createResult?.data?.id;
-            const hints = [
-                "To update fields, use manage_testcase(action='update', ids='<id>', field='<name>', value='<value>')",
-            ];
+            const hints = [];
             if (tcId) {
                 createResult.url = `${getFrontendBaseUrl()}/${projectId}/testcases/${tcId}`;
                 if (testSteps?.length) {
@@ -987,9 +902,14 @@ async function handleManageTestcase(args) {
             if (!Array.isArray(testcases) || testcases.length === 0) {
                 throw new Error("testcases must be a non-empty JSON array");
             }
+            const shared = {};
+            for (const f of BULK_SHARED_FIELDS)
+                if (args[f] !== undefined && args[f] !== null && args[f] !== "")
+                    shared[f] = args[f];
             // Validate everything before creating anything
             const items = [];
-            for (const [i, tc] of testcases.entries()) {
+            for (const [i, item] of testcases.entries()) {
+                const tc = item && typeof item === "object" ? { ...shared, ...item } : item;
                 if (!tc?.title && !tc?.name)
                     throw new Error(`testcases[${i}]: title is required`);
                 try {
@@ -1114,7 +1034,7 @@ async function handleManageTestcase(args) {
                 query: { projectId },
                 body: { stepIds },
             });
-            return jsonResponse(data);
+            return jsonResponse({ ...compact(data), steps: await currentSteps(projectId, tcId) });
         }
         case "reorder_steps": {
             const tcId = validateId(requireArg(args, "testcaseId", ["testcase_id", "id"]), "testcaseId");
@@ -1124,7 +1044,7 @@ async function handleManageTestcase(args) {
             const data = await callApi("put", `projects/testcases/teststeps/${projectId}/${tcId}/reorder`, {
                 body: { stepIds },
             });
-            return jsonResponse(data);
+            return jsonResponse({ ...compact(data), steps: await currentSteps(projectId, tcId) });
         }
         default:
             throw new Error(`Unknown action: ${action}. Use: create, create_bulk, update, delete, add_steps, update_step, delete_steps, reorder_steps`);
@@ -1209,7 +1129,7 @@ async function handleSearchTestCycles(args) {
     validateId(projectId, "projectId");
     const folderId = p(args, "folderId", "folder_id");
     const filters = buildFilters(undefined, {
-        status: p(args, "status"),
+        status: normalizePlanStatus(p(args, "status")),
         folder_id: folderId === undefined || folderId === null || folderId === "" ? undefined : Number(folderId),
     });
     const data = await callApi("get", `projects/test-cycles/get-test-cycles/${projectId}`, {
@@ -1228,7 +1148,7 @@ async function handleSearchTestCycles(args) {
                 cycle.url = `${baseUrl}/${projectId}/testcycles/${id}`;
         });
     }
-    return jsonResponse(data);
+    return listResponse(args, data, LIST_KEYS.cycles, "test_cycle_id");
 }
 // 8. manage_test_cycle
 async function handleManageTestCycle(args) {
@@ -1248,7 +1168,7 @@ async function handleManageTestCycle(args) {
             if (p(args, "summary"))
                 body.summary = p(args, "summary");
             if (p(args, "status"))
-                body.status = p(args, "status");
+                body.status = normalizePlanStatus(p(args, "status"));
             if (p(args, "planned_start_date", "plannedStartDate"))
                 body.planned_start_date = p(args, "planned_start_date", "plannedStartDate");
             if (p(args, "planned_end_date", "plannedEndDate"))
@@ -1268,7 +1188,7 @@ async function handleManageTestCycle(args) {
             if (p(args, "summary"))
                 body.summary = p(args, "summary");
             if (p(args, "status"))
-                body.status = p(args, "status");
+                body.status = normalizePlanStatus(p(args, "status"));
             if (p(args, "planned_start_date", "plannedStartDate"))
                 body.planned_start_date = p(args, "planned_start_date", "plannedStartDate");
             if (p(args, "planned_end_date", "plannedEndDate"))
@@ -1295,7 +1215,7 @@ async function handleManageTestCycle(args) {
             if (data?.data) {
                 data.data.url = `${getFrontendBaseUrl()}/${projectId}/testcycles/${cycleId}`;
             }
-            return jsonResponse(data);
+            return jsonResponse(data, !!p(args, "verbose"));
         }
         case "get_testcases": {
             const cycleId = p(args, "cycleId", "cycle_id", "id");
@@ -1309,7 +1229,7 @@ async function handleManageTestCycle(args) {
                     limit: p(args, "limit"),
                 },
             });
-            return jsonResponse(data);
+            return listResponse(args, data, LIST_KEYS.linkedCases);
         }
         case "link_testcases": {
             const cycleId = p(args, "cycleId", "cycle_id", "id");
@@ -1367,7 +1287,8 @@ async function handleExecuteTests(args) {
         throw new Error("results is required");
     validateId(projectId, "projectId");
     validateId(cycleId, "cycleId");
-    const results = safeJsonParse(resultsRaw, "results");
+    const parsedResults = safeJsonParse(resultsRaw, "results");
+    const results = parsedResults && !Array.isArray(parsedResults) && typeof parsedResults === "object" ? [parsedResults] : parsedResults;
     if (!Array.isArray(results) || results.length === 0) {
         throw new Error("results must be a non-empty array");
     }
@@ -1386,7 +1307,7 @@ async function handleExecuteTests(args) {
         }
         const out = {
             testcase_id: validateId(testcaseId, "testcase_id"),
-            execution_status: status,
+            execution_status: normalizeExecutionStatus(status, `results[${i}]`),
         };
         const actual = r.actual_result || r.actualResult;
         if (actual)
@@ -1438,7 +1359,7 @@ async function handleManageTestPlan(args) {
             if (p(args, "summary"))
                 body.summary = p(args, "summary");
             if (p(args, "status"))
-                body.status = p(args, "status");
+                body.status = normalizePlanStatus(p(args, "status"));
             if (p(args, "planned_start_date", "plannedStartDate"))
                 body.planned_start_date = p(args, "planned_start_date", "plannedStartDate");
             if (p(args, "planned_end_date", "plannedEndDate"))
@@ -1458,7 +1379,7 @@ async function handleManageTestPlan(args) {
             if (p(args, "summary"))
                 body.summary = p(args, "summary");
             if (p(args, "status"))
-                body.status = p(args, "status");
+                body.status = normalizePlanStatus(p(args, "status"));
             if (p(args, "planned_start_date", "plannedStartDate"))
                 body.planned_start_date = p(args, "planned_start_date", "plannedStartDate");
             if (p(args, "planned_end_date", "plannedEndDate"))
@@ -1492,7 +1413,7 @@ async function handleManageTestPlan(args) {
                         plan.url = `${baseUrl}/${projectId}/testplans/${id}`;
                 });
             }
-            return jsonResponse(data);
+            return listResponse(args, data, LIST_KEYS.plans, "test_plan_id");
         }
         case "get_details": {
             const planId = p(args, "planId", "plan_id", "id");
@@ -1503,7 +1424,7 @@ async function handleManageTestPlan(args) {
             if (data?.data) {
                 data.data.url = `${getFrontendBaseUrl()}/${projectId}/testplans/${planId}`;
             }
-            return jsonResponse(data);
+            return jsonResponse(data, !!p(args, "verbose"));
         }
         case "link_cycles": {
             const planId = p(args, "planId", "plan_id", "id");
@@ -1541,7 +1462,7 @@ async function handleManageTestPlan(args) {
                     limit: p(args, "limit"),
                 },
             });
-            return jsonResponse(data);
+            return listResponse(args, data, LIST_KEYS.cycles);
         }
         case "get_testcases": {
             const planId = p(args, "planId", "plan_id", "id");
@@ -1555,7 +1476,7 @@ async function handleManageTestPlan(args) {
                     limit: p(args, "limit"),
                 },
             });
-            return jsonResponse(data);
+            return listResponse(args, data, LIST_KEYS.linkedCases);
         }
         default:
             throw new Error(`Unknown action: ${action}. Use: create, update, delete, list, get_details, link_cycles, unlink_cycles, get_cycles, get_testcases`);
@@ -1603,7 +1524,7 @@ async function handleGetReport(args) {
     const data = await callApi("get", `projects/reports/${endpointPath}/${projectId}`, {
         query,
     });
-    return jsonResponse(data);
+    return jsonResponse(data, !!p(args, "verbose"));
 }
 // ═══════════════════════════════════════════════════════════════════════════════
 // SERVER SETUP