common-qa-mcp 0.4.1 → 0.6.0

package/dist/tools/discovery.tools.js

@@ -17,6 +17,30 @@ function totalOf(rows) {
     const t = rows.totalCount;
     return typeof t === 'number' ? t : undefined;
 }
+/** Render a `ModuleSaved` (single node or subtree) as human-readable text so the model sees the
+ *  full tree shape it just created — id, code, isRoot flag, parent, and nested children indented.
+ *  `failedAt` (if set on root) is surfaced at the bottom so a partial-success is never hidden. */
+function formatModuleSaved(saved, indent = 0) {
+    const pad = '  '.repeat(indent);
+    const code = saved.code ? ` [${saved.code}]` : '';
+    const parent = saved.parentId ? `, parent=${saved.parentId}` : '';
+    const root = saved.isRoot ? ', isRoot=true' : '';
+    const head = `${pad}- ${saved.name}${code} (id ${saved.id}${root}${parent})`;
+    const childLines = (saved.children ?? []).map((c) => formatModuleSaved(c, indent + 1));
+    const parts = [head, ...childLines];
+    if (indent === 0 && saved.failedAt) {
+        parts.push(`\n⚠ Subtree create stopped at "${saved.failedAt.path}": ${saved.failedAt.error}`);
+        parts.push('  Nodes listed above ARE persisted. Fix the error, then create the remaining nodes.');
+    }
+    if (indent === 0) {
+        const created = countCreated(saved);
+        parts.unshift(`Created ${created} module${created === 1 ? '' : 's'}:`);
+    }
+    return parts.join('\n');
+}
+function countCreated(saved) {
+    return 1 + (saved.children ?? []).reduce((n, c) => n + countCreated(c), 0);
+}
 /** Header line for a list tool: "Showing 100 of 350 test cases" when the backend returned a
  *  totalCount larger than the page, else "N test cases". Pluralises via `plural` (defaults to `s`
  *  suffix — pass explicit forms for "stor y/ies", etc). */
@@ -88,7 +112,9 @@ export function registerDiscoveryTools(server, deps) {
             'use `list_functions` instead. Trigger words for THIS tool: "test case", "TC", "TC_", ' +
             '"scenario", "script". Requires a live connection (qa_connect). Returns a summary list — id, ' +
             'title, technology, execution type, status, step count. Use `tc_get` to read one in full. ' +
-            'Read-only, product-neutral.',
+            'Read-only, product-neutral. When presenting this as a table, label the columns "ID" and ' +
+            '"Name" — the underlying fields are literally named `code`/`title`, but that\'s internal ' +
+            'wire terminology, not what to show the user.',
         inputSchema: {
             search: z.string().optional().describe('Free-text search over title / id.'),
             status: z.string().optional().describe('Filter by status.'),
@@ -126,7 +152,7 @@ export function registerDiscoveryTools(server, deps) {
             const obsoleteCount = rows.filter((r) => r.obsolete === true).length;
             const obsoleteNote = obsoleteCount ? ` · ${obsoleteCount} obsolete` : '';
             const text = `${countHeader(rows, 'test case')}${obsoleteNote}:\n\n` +
-                '| key | title | technology | execution | status | steps | obsolete |\n|---|---|---|---|---|---|---|\n' +
+                '| ID | Name | technology | execution | status | steps | obsolete |\n|---|---|---|---|---|---|---|\n' +
                 rows
                     .map((r) => `| ${escCell(r.code)} | ${escCell(r.title)} | ${r.technologyType ?? '-'} | ${r.executionType ?? '-'} | ${r.status ?? '-'} | ${r.stepCount ?? '-'} | ${r.obsolete === true ? 'yes' : ''} |`)
                     .join('\n');
@@ -232,69 +258,55 @@ export function registerDiscoveryTools(server, deps) {
         }
     });
     server.registerTool('tc_clone', {
-        title: 'Clone a test case (copy in place with steps, versions, testdata)',
+        title: 'Save a test case as a new test case (same project + module)',
         description: 'FOR TEST CASES ONLY. NOT for reusable functions: if the user names an `FN_*` key or asks to ' +
             'clone a function, use `fn_clone` instead. Trigger words for THIS tool: "test case", "TC", ' +
             '"TC_", "scenario", "script".\n\n' +
-            'Save an existing test case as a NEW copy in the SAME project + module — all steps, ' +
-            'versions, test data (all environments), parameters, object refs, and nested function ' +
-            "calls are carried over. Uses SimplifyQA's native TC/FN copy endpoint. `tcId` accepts the " +
-            "product's id or business key (`TC_*`).\n\n" +
-            'Naming: pass `newName` for a custom title; otherwise the backend auto-names the copy as ' +
-            '`{sourceName}_copy1`, `_copy2`, etc.\n\n' +
-            'VERSIONS — TWO-STEP: call once WITHOUT `versions` to get a preview of the source\'s ' +
-            'versions and confirm with the user which to clone; then call again with `versions` set. ' +
-            '`versions:["*"]` clones every version; `versions:["v1.0","v2.0",...]` clones only those. ' +
-            'The tool REFUSES to clone until `versions` is passed — the preview step is not skippable.\n\n' +
-            'PERMISSION: requires the `copy_testcase_across_project` privilege on the project (admins ' +
-            "have it by default; other roles need it granted). If you get a permission error, ask your " +
-            'project admin. Requires a live connection.',
+            'Save an existing test case as a NEW test case (new TC id) in the SAME project + module. ' +
+            'Mirrors the FE in-editor "Save as new TC" dialog (operation: SAVEASNEWTC). Clones ONE ' +
+            'source version — pass `sourceVersionId` to pick which; defaults to the TC\'s currently ' +
+            'selected version. `tcId` accepts the numeric id or business key (`TC_*`).\n\n' +
+            '`newName` is REQUIRED — backend rejects an empty name on SAVEASNEWTC.\n\n' +
+            'TESTDATA — TWO-STEP: call once WITHOUT `tdCopy` to get the "Copy Test Data" prompt and ' +
+            'confirm with the user; then call again with `tdCopy` set. Mirrors the FE\'s "COPY TEST ' +
+            'DATA" modal (Cancel = false, Confirm = true). The tool REFUSES to clone until `tdCopy` ' +
+            'is passed — the prompt step is not skippable.\n\n' +
+            '`tdCopy:true` clones the source version\'s testdata iterations across every environment. ' +
+            '`tdCopy:false` copies only the column STRUCTURE — one empty iteration (`ITR-1`) per ' +
+            'environment; cells fall back to each parameter\'s project-level `defaultValue` if any.\n\n' +
+            'Requires a live connection.',
         inputSchema: {
             tcId: z.string().describe('The source test case id or business key (e.g. TC_123).'),
-            newName: z.string().optional().describe('Custom title for the copy. Omit to let the backend auto-name it (`{sourceName}_copy1`).'),
-            versions: z.array(z.string()).optional().describe('REQUIRED to actually clone. Version NAMES to clone (e.g. ["v1.0"]), or ["*"] to clone every version. Omit on the first call to get a preview + version list; ask the user which they want; then call again with the chosen value.'),
+            newName: z.string().min(1).describe('Name for the new test case (required by backend).'),
+            tdCopy: z.boolean().optional().describe('REQUIRED to actually clone. Whether to clone the source version\'s testdata iterations. Omit on the first call to get the confirmation prompt; ask the user, then call again with the chosen value.'),
+            sourceVersionId: z.string().optional().describe('Which version of the source TC to clone; defaults to the TC\'s current version.'),
         },
         annotations: { readOnlyHint: false },
-    }, async ({ tcId, newName, versions }) => {
+    }, async ({ tcId, newName, tdCopy, sourceVersionId }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
         if (!adapter.cloneTestCase)
-            return err('This product does not support test-case clone.');
-        if (!adapter.getTestCase)
-            return err('This product does not support test-case read.');
-        // Preview step: no `versions` → fetch the source's version list and hand it back so the
-        // caller can confirm with the user which to clone. Adapter is not touched for the write.
-        if (versions === undefined) {
-            try {
-                const tc = await adapter.getTestCase(tcId);
-                const names = (tc.versions ?? []).map((v) => v.name);
-                if (names.length === 0) {
-                    return err(`Cannot clone ${tcId}: source has no versions to copy.`);
-                }
-                return ok(`**${tcId}** has ${names.length} version${names.length === 1 ? '' : 's'}: ` +
-                    `${names.map((n) => `\`${n}\``).join(', ')}.\n\n` +
-                    `**Ask the user which version(s) to clone**, then call \`tc_clone\` again:\n` +
-                    `- \`versions: ["*"]\` → clone ALL versions\n` +
-                    `- \`versions: ${JSON.stringify([names[0]])}\` → clone only that version\n` +
-                    `- \`versions: [name1, name2]\` → clone a specific subset`, { preview: true, versions: names, totalCount: names.length });
-            }
-            catch (e) {
-                return err(describeError(e));
-            }
+            return err('This product does not support save-as-new-testcase.');
+        // Prompt step: no `tdCopy` → hand back the "Copy Test Data" question.
+        if (tdCopy === undefined) {
+            return ok(`**COPY TEST DATA** — Do you want to copy test data to new test case **${newName}** (from ${tcId})?\n\n` +
+                `If you do not want to copy the test data, only the column structure will be carried over (one empty ITR-1 per environment).\n\n` +
+                `**Ask the user**, then call \`tc_clone\` again:\n` +
+                `- \`tdCopy: true\` → copy iterations across all environments (Confirm)\n` +
+                `- \`tdCopy: false\` → structure only, empty values (Cancel)`, { preview: true, needs: 'tdCopy' });
         }
-        // Explicit sentinel ["*"] = "all versions" — pass through as undefined to the adapter.
-        const isAll = versions.length === 1 && versions[0] === '*';
-        const effectiveVersions = isAll ? undefined : versions;
         try {
-            const ref = await adapter.cloneTestCase(tcId, newName, effectiveVersions);
-            const nameNote = newName ? ` renamed to **${newName}**` : ' (auto-named by the backend)';
-            const versionNote = isAll
-                ? ' All versions were carried over.'
-                : ` Only version(s) ${versions.map((v) => `**${v}**`).join(', ')} were carried over.`;
-            return ok(`Cloned ${tcId} →${nameNote}. New id: **${ref.id}**` +
+            const ref = await adapter.cloneTestCase(tcId, newName, {
+                tdCopy,
+                ...(sourceVersionId !== undefined ? { sourceVersionId } : {}),
+            });
+            const tdNote = tdCopy
+                ? ' Testdata iterations were copied across environments.'
+                : ' Testdata structure was carried over but values are empty (tdCopy:false).';
+            return ok(`Cloned ${tcId} → **${newName}**. New id: **${ref.id}**` +
                 (ref.productUrl ? ` · ${ref.productUrl}` : '') +
-                `.${versionNote}`, { savedRef: ref });
+                `.${tdNote}`, { savedRef: ref });
         }
         catch (e) {
             return err(describeError(e));
@@ -309,16 +321,19 @@ export function registerDiscoveryTools(server, deps) {
             'new version row with cloned steps. Mirrors the SimplifyQA UI "Save as new version" dialog ' +
             '(operation: SAVENEWVERSION). `tcId` accepts the numeric id or business key (`TC_*`).\n\n' +
             '`versionName` must be unique for this TC — the backend rejects duplicates.\n\n' +
-            '`tdCopy` (default TRUE) clones the source version\'s testdata iterations across every ' +
-            'environment. Pass `false` to copy only the iteration STRUCTURE — values are empty, and ' +
-            'parameters without a project-level defaultValue get suffixed column names. That matches ' +
-            'the FE\'s "Cancel" button on the testdata-copy prompt.\n\n' +
+            'TESTDATA — TWO-STEP: call once WITHOUT `tdCopy` to get the "Copy Test Data" prompt and ' +
+            'confirm with the user; then call again with `tdCopy` set. Mirrors the FE\'s "COPY TEST ' +
+            'DATA" modal (Cancel = false, Confirm = true). The tool REFUSES to snapshot until `tdCopy` ' +
+            'is passed — the prompt step is not skippable.\n\n' +
+            '`tdCopy:true` clones the source version\'s testdata iterations across every environment. ' +
+            '`tdCopy:false` copies only the column STRUCTURE — one empty iteration (`ITR-1`) per ' +
+            'environment; cells fall back to each parameter\'s project-level `defaultValue` if any.\n\n' +
             '`sourceVersionId` picks which version to snapshot; omit to snapshot the TC\'s currently ' +
             'selected version. Requires a live connection.',
         inputSchema: {
             tcId: z.string().describe('The test case id or business key (e.g. TC_123).'),
             versionName: z.string().min(1).describe('Name for the new version (must be unique for this TC).'),
-            tdCopy: z.boolean().optional().describe('Clone testdata iterations from the source version. Default: true.'),
+            tdCopy: z.boolean().optional().describe('REQUIRED to actually snapshot. Clone testdata iterations from the source version. Omit on the first call to get the confirmation prompt; ask the user, then call again with the chosen value.'),
             sourceVersionId: z.string().optional().describe('Version to snapshot; defaults to the TC\'s current version.'),
         },
         annotations: { readOnlyHint: false },
@@ -328,14 +343,22 @@ export function registerDiscoveryTools(server, deps) {
             return err(NOT_CONNECTED);
         if (!adapter.saveAsNewVersion)
             return err('This product does not support save-as-new-version.');
-        const effectiveTdCopy = tdCopy ?? true;
+        // Prompt step: no `tdCopy` → hand back the "Copy Test Data" question so the caller can
+        // confirm with the user before writing. Mirrors the FE's COPY TEST DATA modal.
+        if (tdCopy === undefined) {
+            return ok(`**COPY TEST DATA** — Do you want to copy test data to new version **${versionName}** of ${tcId}?\n\n` +
+                `If you do not want to copy the test data, only the column structure will be carried over (one empty ITR-1 per environment).\n\n` +
+                `**Ask the user**, then call \`tc_save_as_new_version\` again:\n` +
+                `- \`tdCopy: true\` → copy iterations across all environments (Confirm)\n` +
+                `- \`tdCopy: false\` → structure only, empty values (Cancel)`, { preview: true, needs: 'tdCopy' });
+        }
         try {
             const ref = await adapter.saveAsNewVersion(tcId, {
                 versionName,
-                tdCopy: effectiveTdCopy,
+                tdCopy,
                 ...(sourceVersionId !== undefined ? { sourceVersionId } : {}),
             });
-            const tdNote = effectiveTdCopy
+            const tdNote = tdCopy
                 ? ' Testdata iterations were copied across environments.'
                 : ' Testdata structure was carried over but values are empty (tdCopy:false).';
             return ok(`Snapshotted ${tcId} as new version **${versionName}**` +
@@ -746,69 +769,55 @@ export function registerDiscoveryTools(server, deps) {
         }
     });
     server.registerTool('fn_clone', {
-        title: 'Clone a reusable function (copy in place with steps, versions, testdata)',
+        title: 'Save a reusable function as a new function (same project + module)',
         description: 'FOR REUSABLE FUNCTIONS ONLY. NOT for test cases: if the user names a `TC_*` key or asks to ' +
             'clone a test case / scenario / script, use `tc_clone` instead. Trigger words for THIS tool: ' +
             '"function", "reusable function", "FN_", "FN-".\n\n' +
-            'Save an existing reusable FUNCTION as a NEW copy in the SAME project + module — all steps, ' +
-            'versions, test data (all environments), parameters, object refs, and nested function calls ' +
-            "are carried over. Uses SimplifyQA's native TC/FN copy endpoint with `type:'FN'`. `fnId` " +
-            "accepts the product's id or business key (`FN_*`).\n\n" +
-            'Naming: pass `newName` for a custom title; otherwise the backend auto-names the copy as ' +
-            '`{sourceName}_copy1`, `_copy2`, etc.\n\n' +
-            'VERSIONS — TWO-STEP: call once WITHOUT `versions` to get a preview of the source\'s ' +
-            'versions and confirm with the user which to clone; then call again with `versions` set. ' +
-            '`versions:["*"]` clones every version; `versions:["v1.0","v2.0",...]` clones only those. ' +
-            'The tool REFUSES to clone until `versions` is passed — the preview step is not skippable.\n\n' +
-            'PERMISSION: requires the `copy_function_across_projects` privilege on the project (admins ' +
-            "have it by default; other roles need it granted). If you get a permission error, ask your " +
-            'project admin. Requires a live connection.',
+            'Save an existing reusable FUNCTION as a NEW function (new FN id) in the SAME project + ' +
+            'module. Mirrors the FE in-editor "Save as new function" dialog (operation: SAVEASNEWFN). ' +
+            'Clones ONE source version — pass `sourceVersionId` to pick which; defaults to the FN\'s ' +
+            'newest version. `fnId` accepts the numeric id or business key (`FN_*`).\n\n' +
+            '`newName` is REQUIRED — backend rejects an empty name on SAVEASNEWFN.\n\n' +
+            'TESTDATA — TWO-STEP: call once WITHOUT `tdCopy` to get the "Copy Test Data" prompt and ' +
+            'confirm with the user; then call again with `tdCopy` set. Mirrors the FE\'s "COPY TEST ' +
+            'DATA" modal (Cancel = false, Confirm = true). The tool REFUSES to clone until `tdCopy` ' +
+            'is passed — the prompt step is not skippable.\n\n' +
+            '`tdCopy:true` clones the source version\'s testdata iterations across every environment. ' +
+            '`tdCopy:false` copies only the column STRUCTURE — one empty iteration (`ITR-1`) per ' +
+            'environment; cells fall back to each parameter\'s project-level `defaultValue` if any.\n\n' +
+            'Requires a live connection.',
         inputSchema: {
             fnId: z.string().describe('The source function id or business key (e.g. FN_123).'),
-            newName: z.string().optional().describe('Custom title for the copy. Omit to let the backend auto-name it (`{sourceName}_copy1`).'),
-            versions: z.array(z.string()).optional().describe('REQUIRED to actually clone. Version NAMES to clone (e.g. ["v1.0"]), or ["*"] to clone every version. Omit on the first call to get a preview + version list; ask the user which they want; then call again with the chosen value.'),
+            newName: z.string().min(1).describe('Name for the new function (required by backend).'),
+            tdCopy: z.boolean().optional().describe('REQUIRED to actually clone. Whether to clone the source version\'s testdata iterations. Omit on the first call to get the confirmation prompt; ask the user, then call again with the chosen value.'),
+            sourceVersionId: z.string().optional().describe('Which version of the source FN to clone; defaults to the FN\'s newest version.'),
         },
         annotations: { readOnlyHint: false },
-    }, async ({ fnId, newName, versions }) => {
+    }, async ({ fnId, newName, tdCopy, sourceVersionId }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
         if (!adapter.cloneFunction)
-            return err('This product does not support function clone.');
-        if (!adapter.getFunction)
-            return err('This product has no reusable-function library.');
-        // Preview step: no `versions` → fetch the source's version list via get_function (which
-        // hydrates `versions` from `/tm/function/version/:id/:pid`) and hand it back.
-        if (versions === undefined) {
-            try {
-                const fn = await adapter.getFunction(fnId);
-                const names = (fn.versions ?? []).map((v) => v.name);
-                if (names.length === 0) {
-                    return err(`Cannot clone ${fnId}: source has no versions to copy.`);
-                }
-                return ok(`**${fnId}** has ${names.length} version${names.length === 1 ? '' : 's'}: ` +
-                    `${names.map((n) => `\`${n}\``).join(', ')}.\n\n` +
-                    `**Ask the user which version(s) to clone**, then call \`fn_clone\` again:\n` +
-                    `- \`versions: ["*"]\` → clone ALL versions\n` +
-                    `- \`versions: ${JSON.stringify([names[0]])}\` → clone only that version\n` +
-                    `- \`versions: [name1, name2]\` → clone a specific subset`, { preview: true, versions: names, totalCount: names.length });
-            }
-            catch (e) {
-                return err(describeError(e));
-            }
+            return err('This product does not support save-as-new-function.');
+        // Prompt step: no `tdCopy` → hand back the "Copy Test Data" question.
+        if (tdCopy === undefined) {
+            return ok(`**COPY TEST DATA** — Do you want to copy test data to new function **${newName}** (from ${fnId})?\n\n` +
+                `If you do not want to copy the test data, only the column structure will be carried over (one empty ITR-1 per environment).\n\n` +
+                `**Ask the user**, then call \`fn_clone\` again:\n` +
+                `- \`tdCopy: true\` → copy iterations across all environments (Confirm)\n` +
+                `- \`tdCopy: false\` → structure only, empty values (Cancel)`, { preview: true, needs: 'tdCopy' });
         }
-        // Explicit sentinel ["*"] = "all versions" — pass through as undefined to the adapter.
-        const isAll = versions.length === 1 && versions[0] === '*';
-        const effectiveVersions = isAll ? undefined : versions;
         try {
-            const ref = await adapter.cloneFunction(fnId, newName, effectiveVersions);
-            const nameNote = newName ? ` renamed to **${newName}**` : ' (auto-named by the backend)';
-            const versionNote = isAll
-                ? ' All versions were carried over.'
-                : ` Only version(s) ${versions.map((v) => `**${v}**`).join(', ')} were carried over.`;
-            return ok(`Cloned ${fnId} →${nameNote}. New id: **${ref.id}**` +
+            const ref = await adapter.cloneFunction(fnId, newName, {
+                tdCopy,
+                ...(sourceVersionId !== undefined ? { sourceVersionId } : {}),
+            });
+            const tdNote = tdCopy
+                ? ' Testdata iterations were copied across environments.'
+                : ' Testdata structure was carried over but values are empty (tdCopy:false).';
+            return ok(`Cloned ${fnId} → **${newName}**. New id: **${ref.id}**` +
                 (ref.productUrl ? ` · ${ref.productUrl}` : '') +
-                `.${versionNote}`, { savedRef: ref });
+                `.${tdNote}`, { savedRef: ref });
         }
         catch (e) {
             return err(describeError(e));
@@ -823,15 +832,19 @@ export function registerDiscoveryTools(server, deps) {
             'new version row with cloned steps. Mirrors the SimplifyQA UI "Save as new version" dialog ' +
             '(operation: SAVENEWVERSION, type: FN). `fnId` accepts the numeric id or business key (`FN_*`).\n\n' +
             '`versionName` must be unique for this FN — the backend rejects duplicates.\n\n' +
-            '`tdCopy` (default TRUE) clones the source version\'s testdata iterations across every ' +
-            'environment. Pass `false` to copy only the iteration STRUCTURE — values are empty. That ' +
-            'matches the FE\'s "Cancel" button on the testdata-copy prompt.\n\n' +
+            'TESTDATA — TWO-STEP: call once WITHOUT `tdCopy` to get the "Copy Test Data" prompt and ' +
+            'confirm with the user; then call again with `tdCopy` set. Mirrors the FE\'s "COPY TEST ' +
+            'DATA" modal (Cancel = false, Confirm = true). The tool REFUSES to snapshot until `tdCopy` ' +
+            'is passed — the prompt step is not skippable.\n\n' +
+            '`tdCopy:true` clones the source version\'s testdata iterations across every environment. ' +
+            '`tdCopy:false` copies only the column STRUCTURE — one empty iteration (`ITR-1`) per ' +
+            'environment; cells fall back to each parameter\'s project-level `defaultValue` if any.\n\n' +
             '`sourceVersionId` picks which version to snapshot; omit to snapshot the FN\'s newest ' +
             'version (the FN doc has no inline current-version marker). Requires a live connection.',
         inputSchema: {
             fnId: z.string().describe('The function id or business key (e.g. FN_123).'),
             versionName: z.string().min(1).describe('Name for the new version (must be unique for this FN).'),
-            tdCopy: z.boolean().optional().describe('Clone testdata iterations from the source version. Default: true.'),
+            tdCopy: z.boolean().optional().describe('REQUIRED to actually snapshot. Clone testdata iterations from the source version. Omit on the first call to get the confirmation prompt; ask the user, then call again with the chosen value.'),
             sourceVersionId: z.string().optional().describe('Version to snapshot; defaults to the FN\'s newest version.'),
         },
         annotations: { readOnlyHint: false },
@@ -841,14 +854,22 @@ export function registerDiscoveryTools(server, deps) {
             return err(NOT_CONNECTED);
         if (!adapter.saveAsNewFunctionVersion)
             return err('This product does not support save-as-new-version for functions.');
-        const effectiveTdCopy = tdCopy ?? true;
+        // Prompt step: no `tdCopy` → hand back the "Copy Test Data" question so the caller can
+        // confirm with the user before writing. Mirrors the FE's COPY TEST DATA modal.
+        if (tdCopy === undefined) {
+            return ok(`**COPY TEST DATA** — Do you want to copy test data to new version **${versionName}** of ${fnId}?\n\n` +
+                `If you do not want to copy the test data, only the column structure will be carried over (one empty ITR-1 per environment).\n\n` +
+                `**Ask the user**, then call \`fn_save_as_new_version\` again:\n` +
+                `- \`tdCopy: true\` → copy iterations across all environments (Confirm)\n` +
+                `- \`tdCopy: false\` → structure only, empty values (Cancel)`, { preview: true, needs: 'tdCopy' });
+        }
         try {
             const ref = await adapter.saveAsNewFunctionVersion(fnId, {
                 versionName,
-                tdCopy: effectiveTdCopy,
+                tdCopy,
                 ...(sourceVersionId !== undefined ? { sourceVersionId } : {}),
             });
-            const tdNote = effectiveTdCopy
+            const tdNote = tdCopy
                 ? ' Testdata iterations were copied across environments.'
                 : ' Testdata structure was carried over but values are empty (tdCopy:false).';
             return ok(`Snapshotted ${fnId} as new version **${versionName}**` +
@@ -878,8 +899,12 @@ export function registerDiscoveryTools(server, deps) {
             if (!rows.length)
                 return ok('No modules found.', { modules: [], totalCount: totalOf(rows) ?? 0 });
             const text = `${countHeader(rows, 'module')}:\n\n` +
-                '| id | name | parent |\n|---|---|---|\n' +
-                rows.map((m) => `| ${escCell(m.id)} | ${escCell(m.name)} | ${escCell(m.parentId ?? '-')} |`).join('\n');
+                '| id | name | type | parent | childIds |\n|---|---|---|---|---|\n' +
+                rows.map((m) => {
+                    const type = m.isRoot ? 'root' : m.parentId ? 'sub' : '-';
+                    const children = m.childIds?.length ? m.childIds.join(', ') : '-';
+                    return `| ${escCell(m.id)} | ${escCell(m.name)} | ${type} | ${escCell(m.parentId ?? '-')} | ${escCell(children)} |`;
+                }).join('\n');
             return ok(text, { modules: rows, totalCount: totalOf(rows) ?? rows.length });
         }
         catch (e) {
@@ -916,19 +941,29 @@ export function registerDiscoveryTools(server, deps) {
             return err(describeError(e));
         }
     });
+    const zModuleChild = z.lazy(() => z.object({
+        name: z.string().min(1),
+        description: z.string().optional(),
+        children: z.array(zModuleChild).optional(),
+    }));
     server.registerTool('create_module', {
-        title: 'Create a module (folder) in the test-case tree',
+        title: 'Create a module (folder), optionally with a nested subtree, in the test-case tree',
         description: 'Create a new MODULE under the connected project. Set `isRoot:true` for a top-level folder; ' +
-            'otherwise pass `parentId` (resolve via list_modules). Duplicate name in the same project is ' +
-            'rejected server-side. SimplifyQA-only. Requires a live connection.',
+            'otherwise pass `parentId` (resolve via list_modules). To create a WHOLE HIERARCHY in one call ' +
+            '(root + submodules + nested submodules), pass a `children` array — each child gets ' +
+            '`isRoot:false` and its parentId auto-wired from the tree position (do NOT set `isRoot`/`parentId` ' +
+            'on child nodes). Duplicate name in the same project is rejected server-side. On mid-subtree ' +
+            'failure the response carries `failedAt`; every node before it is already persisted (no ' +
+            'transactional rollback upstream). SimplifyQA-only. Requires a live connection.',
         inputSchema: {
             name: z.string().min(1).describe('Module name. Must be unique within the project.'),
             projectId: z.string().describe('Target project id (see list_projects).'),
             isRoot: z.boolean().describe('True → top-level folder; false → child of `parentId`.'),
-            parentId: z.string().optional().describe('Parent module id (required when isRoot is false).'),
+            parentId: z.string().optional().describe('Parent module id (required when isRoot is false; MUST be omitted when isRoot is true).'),
             description: z.string().optional().describe('Free-text description.'),
+            children: z.array(zModuleChild).optional().describe('Optional subtree under this module. Each child = { name, description?, children? } — no isRoot/parentId (derived).'),
         },
-    }, async ({ name, projectId, isRoot, parentId, description }) => {
+    }, async ({ name, projectId, isRoot, parentId, description, children }) => {
         const adapter = deps.getAdapter();
         if (!adapter)
             return err(NOT_CONNECTED);
@@ -937,6 +972,9 @@ export function registerDiscoveryTools(server, deps) {
         if (!isRoot && !parentId) {
             return err('parentId is required when isRoot is false.');
         }
+        if (isRoot && parentId) {
+            return err('parentId must be omitted when isRoot is true — backend silently drops it and the module would land at root, not under the intended parent.');
+        }
         try {
             const saved = await adapter.createModule({
                 name,
@@ -944,8 +982,41 @@ export function registerDiscoveryTools(server, deps) {
                 isRoot,
                 ...(parentId ? { parentId } : {}),
                 ...(description ? { description } : {}),
+                ...(children?.length ? { children } : {}),
+            });
+            return ok(formatModuleSaved(saved), { saved });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
+    server.registerTool('update_module', {
+        title: 'Update a module (rename / edit description)',
+        description: 'Edit an existing MODULE — pass `id` plus any of `name`, `description`. Name must remain ' +
+            'unique within the project (duplicate rejected server-side). SimplifyQA-only. Requires a ' +
+            'live connection.',
+        inputSchema: {
+            id: z.string().describe('Module id (numeric or business key, e.g. MO_12).'),
+            name: z.string().min(1).optional().describe('New module name.'),
+            description: z.string().optional().describe('New description (pass "" to clear).'),
+            projectId: z.string().optional().describe('Project id; defaults to the connected project.'),
+        },
+    }, async ({ id, name, description, projectId }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.updateModule)
+            return err('This product has no module tree.');
+        if (name === undefined && description === undefined) {
+            return err('Nothing to update — pass at least `name` or `description`.');
+        }
+        try {
+            const saved = await adapter.updateModule(id, {
+                ...(name !== undefined ? { name } : {}),
+                ...(description !== undefined ? { description } : {}),
+                ...(projectId ? { projectId } : {}),
             });
-            return ok(`Created module ${saved.id} (${name}).`, { saved });
+            return ok(`Updated module ${saved.id || id}.`, { saved });
         }
         catch (e) {
             return err(describeError(e));
@@ -1084,9 +1155,10 @@ export function registerDiscoveryTools(server, deps) {
     server.registerTool('suite_list', {
         title: 'List test suites',
         description: 'List the test suites in the connected product — id, name, type (Manual/Automation, where the ' +
-            'provider has a suite-level type — SimplifyQA does, Walnut doesn\'t), and member (test-case) ' +
-            'count. Use suite_get to read one with its ordered members, or suite_run to execute one. ' +
-            'Requires a live connection (qa_connect). Read-only and product-neutral.',
+            'provider has a suite-level type — SimplifyQA does, Walnut doesn\'t), and number of test ' +
+            'cases. Use suite_get to read one with its ordered test cases, or suite_run to execute one. ' +
+            'Requires a live connection (qa_connect). Read-only and product-neutral. When presenting this ' +
+            'as a table, label the count column "Number of testcases", not "Members".',
         inputSchema: {},
         annotations: { readOnlyHint: true },
     }, async () => {
@@ -1098,7 +1170,7 @@ export function registerDiscoveryTools(server, deps) {
             if (!rows.length)
                 return ok('No test suites found.', { suites: [], totalCount: totalOf(rows) ?? 0 });
             const text = `${countHeader(rows, 'suite')}:\n\n` +
-                '| id | name | type | test cases |\n|---|---|---|---|\n' +
+                '| id | name | type | Number of testcases |\n|---|---|---|---|\n' +
                 rows.map((s) => `| ${escCell(s.id)} | ${escCell(s.name)} | ${escCell(s.suiteType ?? '-')} | ${s.memberCount ?? '-'} |`).join('\n');
             return ok(text, { suites: rows, totalCount: totalOf(rows) ?? rows.length });
         }
@@ -1145,8 +1217,8 @@ export function registerDiscoveryTools(server, deps) {
         }
     });
     server.registerTool('suite_get', {
-        title: 'Read one test suite (with members)',
-        description: 'Read a single test suite — its name, description, and ORDERED member test cases — from the ' +
+        title: 'Read one test suite (with test cases)',
+        description: 'Read a single test suite — its name, description, and ORDERED test cases — from the ' +
             'connected product. Requires a live connection (qa_connect). `id` is the suite id. ' +
             'Product-neutral: same shape on any connected product.',
         inputSchema: {
@@ -1172,10 +1244,105 @@ export function registerDiscoveryTools(server, deps) {
             return err(describeError(e));
         }
     });
+    server.registerTool('suite_create', {
+        title: 'Create a new suite from a few test cases',
+        description: 'Create a NEW test suite in the connected project from a small set of existing test cases. ' +
+            '`tcIds` accepts numeric ids, business keys (TC_123), OR plain test case NAMES — a name is ' +
+            'resolved by searching the project (tc_list under the hood); an ambiguous name (multiple ' +
+            'matches) or one with zero matches is reported back rather than guessed. NOTE: a suite can ' +
+            'only hold test cases of ONE category (all manual OR all automated) — a mixed set is refused.\n\n' +
+            'NAME: if `name` is omitted, this tool does NOT create anything yet — it resolves the test ' +
+            'cases, SUGGESTS a suite name, and returns a preview. Show the user the suggested name and the ' +
+            'resolved test cases, ask them to confirm it or give their own, then call suite_create again ' +
+            'with `name` set (and the same `tcIds`) to actually create it. Requires a live connection.',
+        inputSchema: {
+            tcIds: z.array(z.string()).min(1).describe('Test case ids, business keys (TC_123), or plain names to include.'),
+            name: z.string().optional().describe('Suite name. Omit to get a suggested name + preview first (does not create).'),
+            description: z.string().optional().describe('Optional suite description.'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async ({ tcIds, name, description }) => {
+        const adapter = deps.getAdapter();
+        if (!adapter)
+            return err(NOT_CONNECTED);
+        if (!adapter.createSuite)
+            return err('This product does not support creating suites.');
+        if (!adapter.getTestCase)
+            return err('This product does not support test-case read.');
+        // Resolve each ref: try it as an id/business key first, else search by name.
+        const resolved = [];
+        const unresolved = [];
+        for (const ref of tcIds) {
+            try {
+                const tc = await adapter.getTestCase(ref);
+                resolved.push({ tcId: tc.id ?? ref, title: tc.title || ref, category: tc.category === 'manual' ? 'manual' : 'automated' });
+                continue;
+            }
+            catch {
+                // Not a direct id/key hit — fall through to a name search below.
+            }
+            if (adapter.listTestCases) {
+                try {
+                    const matches = await adapter.listTestCases({ search: ref, limit: 5 });
+                    if (matches.length === 1) {
+                        const m = matches[0];
+                        const category = String(m.executionType ?? '').toUpperCase() === 'MANUAL' ? 'manual' : 'automated';
+                        resolved.push({ tcId: m.id, title: m.title, category });
+                        continue;
+                    }
+                    if (matches.length > 1) {
+                        return err(`"${ref}" matches ${matches.length} test cases — be more specific or pass the id: ` +
+                            matches.map((m) => `${m.title} (${m.id})`).join(', '));
+                    }
+                }
+                catch {
+                    // fall through to unresolved
+                }
+            }
+            unresolved.push(ref);
+        }
+        if (unresolved.length) {
+            return err(`Could not find a test case for: ${unresolved.join(', ')} — check the id/name, or use ` +
+                'tc_list to search first.');
+        }
+        // Same rule the backend enforces: a suite can only hold ONE category. Catch a mismatch here,
+        // before suggesting a name / asking the user to confirm — no point previewing a suite that
+        // createSuite would refuse anyway.
+        const categories = new Set(resolved.map((r) => r.category));
+        if (categories.size > 1) {
+            const byCategory = (cat) => resolved.filter((r) => r.category === cat).map((r) => `${r.title} (${r.tcId})`).join(', ') || '(none)';
+            return err('Cannot create suite: the test cases are a mix of manual and automated — a suite can only ' +
+                `hold ONE category. Manual: ${byCategory('manual')}. Automated: ${byCategory('automated')}. ` +
+                'Split them into two suites, or pick only same-category test cases.');
+        }
+        if (!name) {
+            const suggested = resolved.length === 1
+                ? `${resolved[0].title} Suite`
+                : `${resolved[0].title} + ${resolved.length - 1} more Suite`;
+            return ok(`Resolved ${resolved.length} test case${resolved.length === 1 ? '' : 's'}: ` +
+                `${resolved.map((r) => `${r.title} (${r.tcId})`).join(', ')}.\n\n` +
+                `Suggested suite name: "${suggested}" — ASK the user to confirm this or give their own ` +
+                `name, then call suite_create again with { name, tcIds } (reuse the same tcIds, or the ` +
+                `resolved ids: ${resolved.map((r) => r.tcId).join(', ')}).`, { preview: true, suggestedName: suggested, testCases: resolved });
+        }
+        try {
+            const ref = await adapter.createSuite({
+                name,
+                ...(description !== undefined ? { description } : {}),
+                members: resolved.map((r, i) => ({ tcId: r.tcId, order: i + 1 })),
+            });
+            return ok(`Created suite **${name}**${ref.id ? ` · ${ref.id}` : ''} with ${resolved.length} test ` +
+                `case${resolved.length === 1 ? '' : 's'}: ${resolved.map((r) => r.title).join(', ')}.` +
+                (ref.productUrl ? ` ${ref.productUrl}` : ''), { savedRef: ref });
+        }
+        catch (e) {
+            return err(describeError(e));
+        }
+    });
     // --- Suite membership edits (writes) --------------------------------------
     // Kept beside suite_list/suite_get so all suite tools live together; they mutate
     // via the adapter's updateSuiteMembers (→ update_suite_members provider-op).
-    const membersTable = (suite) => suite.members.length
+    const testCasesTable = (suite) => suite.members.length
         ? '\n\n| order | test case |\n|---|---|\n' +
             suite.members.map((m) => `| ${m.order} | ${escCell(m.tcId)} |`).join('\n')
         : '';
@@ -1184,7 +1351,7 @@ export function registerDiscoveryTools(server, deps) {
         description: 'Add one or more EXISTING test cases to a suite (appended in order). `tcIds` accepts ids or ' +
             'business keys (e.g. TC_123) — use suite_list / tc_list to find them. NOTE: a suite can only ' +
             'hold test cases of ONE category (all manual OR all automated) — the product rejects a mix. ' +
-            'Requires a live connection. Returns the updated suite with its members.',
+            'Requires a live connection. Returns the updated suite with its test cases.',
         inputSchema: {
             suiteId: z.string().describe('The suite id to add to (from suite_list).'),
             tcIds: z.array(z.string()).min(1).describe('Test case ids / business keys to add.'),
@@ -1209,8 +1376,8 @@ export function registerDiscoveryTools(server, deps) {
                 }
             }));
             return ok(`Added ${added.length} test case${added.length === 1 ? '' : 's'} to **${suite.name}**: ` +
-                `${added.join(', ')} — now ${n} member${n === 1 ? '' : 's'}.` +
-                membersTable(suite), { suite });
+                `${added.join(', ')} — now ${n} test case${n === 1 ? '' : 's'} total.` +
+                testCasesTable(suite), { suite });
         }
         catch (e) {
             return err(describeError(e));
@@ -1219,8 +1386,8 @@ export function registerDiscoveryTools(server, deps) {
     server.registerTool('suite_remove_testcases', {
         title: 'Remove test cases from a suite',
         description: 'Remove one or more test cases from a suite. `tcIds` accepts ids or business keys; every ' +
-            'occurrence of each is removed and the remaining members are reordered. Requires a live ' +
-            'connection. Returns the updated suite with its members.',
+            'occurrence of each is removed and the remaining test cases are reordered. Requires a live ' +
+            'connection. Returns the updated suite with its test cases.',
         inputSchema: {
             suiteId: z.string().describe('The suite id to remove from.'),
             tcIds: z.array(z.string()).min(1).describe('Test case ids / business keys to remove.'),
@@ -1234,8 +1401,8 @@ export function registerDiscoveryTools(server, deps) {
             const ops = tcIds.map((tcId) => ({ op: 'remove', tcId }));
             const suite = await adapter.updateSuiteMembers(suiteId, ops);
             const n = suite.members.length;
-            return ok(`Removed ${tcIds.length} test case${tcIds.length === 1 ? '' : 's'} from **${suite.name}** — now ${n} member${n === 1 ? '' : 's'}.` +
-                membersTable(suite), { suite });
+            return ok(`Removed ${tcIds.length} test case${tcIds.length === 1 ? '' : 's'} from **${suite.name}** — now ${n} test case${n === 1 ? '' : 's'} total.` +
+                testCasesTable(suite), { suite });
         }
         catch (e) {
             return err(describeError(e));