deepline 0.1.35 → 0.1.36

package/dist/cli/index.js

@@ -216,8 +216,8 @@ function resolveConfig(options) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.35";
-var SDK_API_CONTRACT = "2026-05-v2-tool-result-contract";
+var SDK_VERSION = "0.1.36";
+var SDK_API_CONTRACT = "2026-05-v2-tool-response";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
@@ -528,7 +528,7 @@ function sleep(ms) {
 var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
 var EXECUTE_RESPONSE_CONTRACT_HEADER = "x-deepline-execute-response-contract";
-var V2_EXECUTE_RESPONSE_CONTRACT = "v2-tool-execution-result";
+var V2_EXECUTE_RESPONSE_CONTRACT = "v2-tool-response";
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 function sleep2(ms) {
   return new Promise((resolve11) => setTimeout(resolve11, ms));
@@ -797,8 +797,8 @@ var DeeplineClient = class {
   /**
    * Execute a tool and return the standard execution envelope.
    *
-   * The `toolExecutionResult.toolOutput.raw` field contains the raw tool output.
-   * `toolExecutionResult.toolOutput.meta` contains tool/provider metadata.
+   * The `toolResponse.raw` field contains the raw tool response.
+   * `toolResponse.meta` contains tool/provider metadata.
    * Top-level fields such as `status`, `job_id`, and `billing` describe the
    * Deepline execution envelope.
    */
@@ -6587,6 +6587,7 @@ function buildRunNextCommands(status) {
   }
   const commands = {
     get: `deepline runs get ${runId} --json`,
+    full: `deepline runs get ${runId} --full --json`,
     stop: `deepline runs stop ${runId} --reason "stale lock" --json`,
     logs: `deepline runs logs ${runId} --out run.log --json`
   };
@@ -7281,6 +7282,10 @@ function renderServerResultView(value) {
     );
   }
   const tables = Array.isArray(view.tables) ? view.tables : [];
+  const topLevelOutputTable = view.topLevelOutputTable && typeof view.topLevelOutputTable === "object" && !Array.isArray(view.topLevelOutputTable) ? view.topLevelOutputTable : null;
+  if (typeof topLevelOutputTable?.queryCommand === "string") {
+    lines.push(`    top-level outputs: ${topLevelOutputTable.queryCommand}`);
+  }
   if (tables.length > 0) {
     lines.push("    tables:");
     for (const table of tables.slice(0, 6)) {
@@ -7297,6 +7302,21 @@ function renderServerResultView(value) {
       lines.push(
         `    ${String(table.tableNamespace ?? "table")}${lineLabel}: ${rowLabel}${details.join("  ")}`
       );
+      if (typeof table.queryDatasetCommand === "string") {
+        lines.push(`      inspect rows: ${table.queryDatasetCommand}`);
+      }
+      if (table.debugHelp && typeof table.debugHelp === "object" && !Array.isArray(table.debugHelp)) {
+        const debugHelp = table.debugHelp;
+        const rawResultFields = Array.isArray(debugHelp.rawResultFields) ? debugHelp.rawResultFields.filter(
+          (field) => typeof field === "string"
+        ) : [];
+        if (rawResultFields.length > 0) {
+          lines.push(`      tool-result columns: ${rawResultFields.join(", ")}`);
+        }
+      }
+      if (typeof table.slowExportAsCsvCommand === "string") {
+        lines.push(`      export rows: ${table.slowExportAsCsvCommand}`);
+      }
     }
   }
   return { lines: lines.length > 1 ? lines : [], actions: [] };
@@ -7322,7 +7342,8 @@ function writeStartedPlayRun(input) {
     `  get status: deepline runs get ${input.runId} --json`,
     `  logs: deepline runs logs ${input.runId} --json`,
     `  stop run: deepline runs stop ${input.runId} --reason "stale lock" --json`,
-    `  result JSON: deepline runs get ${input.runId} --json`
+    `  result JSON: deepline runs get ${input.runId} --json`,
+    `  full debug JSON: deepline runs get ${input.runId} --full --json`
   ];
   if (input.dashboardUrl) {
     lines.push(`  play page: ${input.dashboardUrl}`);
@@ -8960,17 +8981,13 @@ function normalizeRows(value) {
 }
 function candidateRoots(payload) {
   const roots = [{ path: null, value: payload }];
-  if (isPlainObject(payload) && isPlainObject(payload.toolExecutionResult)) {
-    roots.push({ path: "toolExecutionResult", value: payload.toolExecutionResult });
-    const toolOutput = payload.toolExecutionResult.toolOutput;
-    if (isPlainObject(toolOutput)) {
-      roots.push({ path: "toolExecutionResult.toolOutput", value: toolOutput });
-      if (Object.prototype.hasOwnProperty.call(toolOutput, "raw")) {
-        roots.push({
-          path: "toolExecutionResult.toolOutput.raw",
-          value: toolOutput.raw
-        });
-      }
+  if (isPlainObject(payload) && isPlainObject(payload.toolResponse)) {
+    roots.push({ path: "toolResponse", value: payload.toolResponse });
+    if (Object.prototype.hasOwnProperty.call(payload.toolResponse, "raw")) {
+      roots.push({
+        path: "toolResponse.raw",
+        value: payload.toolResponse.raw
+      });
     }
   }
   if (isPlainObject(payload) && isPlainObject(payload.output)) {
@@ -9276,7 +9293,7 @@ Notes:
   waterfalls, row maps, checkpoints, and retries.
   execute is the canonical execution verb. run is a compatibility alias.
   Calling a provider-backed tool can spend Deepline credits. Use --json for the
-  stable result payload and --full-output when debugging response metadata.
+  stable result payload plus output preview and debugging helpers.
 
 Examples:
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
@@ -9289,7 +9306,7 @@ Examples:
   }, []).option("--json [payload]", "Emit JSON output. Use `--input` or `--payload` for passing JSON params.").option("--input <payload>", "Merge a JSON object into the tool params").option("--payload <payload>", "Merge a JSON object into the tool params").option(
     "--output-format <format>",
     "Output format: auto, csv, csv_file, json, or json_file"
-  ).option("--full-output", "Emit the full JSON payload").option("--no-preview", "Only print the extracted output path when applicable").action(async (toolId, options) => {
+  ).option("--no-preview", "Only print the extracted output path when applicable").action(async (toolId, options) => {
     const args = [
       toolId,
       ...options.param.flatMap((value) => ["--param", value]),
@@ -9298,7 +9315,6 @@ Examples:
       ...options.input ? ["--input", options.input] : [],
       ...options.payload ? ["--payload", options.payload] : [],
       ...options.outputFormat ? ["--output-format", options.outputFormat] : [],
-      ...options.fullOutput ? ["--full-output"] : [],
       ...options.preview === false ? ["--no-preview"] : []
     ];
     process.exitCode = await executeTool(args);
@@ -9323,13 +9339,29 @@ async function getTool(args) {
     throw error;
   }
   if (argsWantJson(args)) {
-    process.stdout.write(`${JSON.stringify(tool)}
+    process.stdout.write(`${JSON.stringify(toolMetadataJsonForDescribe(tool, toolId))}
 `);
     return 0;
   }
   printToolDetails(tool, toolId);
   return 0;
 }
+function toolMetadataJsonForDescribe(tool, requestedToolId) {
+  const toolId = String(tool.toolId || requestedToolId);
+  return {
+    ...tool,
+    toolId,
+    provider: tool.provider,
+    displayName: tool.displayName,
+    runtimeOutputHelp: {
+      contract: "tools describe shows the declared schema and semantic getters; it is not an observed provider response.",
+      observeActualShape: `deepline tools execute ${toolId} --input '{...}' --json`,
+      observedOutput: `deepline tools execute ${toolId} --input '{...}' --json`,
+      forPlayGetterBugs: "Run the play, then inspect the emitted table commands from runs get. Use deepline db query against the run tables before editing getters.",
+      executeOutputFields: "tools execute JSON may include output_preview for this direct probe only; play debugging uses run tables."
+    }
+  };
+}
 function printToolDetails(tool, requestedToolId) {
   const toolId = String(tool.toolId || requestedToolId);
   const operation = typeof tool.operation === "string" ? tool.operation : "";
@@ -9350,6 +9382,10 @@ function printToolDetails(tool, requestedToolId) {
   const samples = recordField(tool, "samples");
   const usageGuidance = recordField(tool, "usageGuidance", "usage_guidance");
   console.log(`Tool: ${toolId}`);
+  console.log("  Runtime output help:");
+  console.log("    describe shows declared schema/getters, not an observed provider response");
+  console.log(`    observe actual shape: deepline tools execute ${toolId} --input '{...}' --json`);
+  console.log("    for play getter bugs: run the play, then use the db query commands printed by runs get");
   if (displayName) {
     console.log("  Display name:");
     console.log(`    ${displayName}`);
@@ -9446,32 +9482,18 @@ function printUsageGuidance(usageGuidance) {
   if (Object.keys(usageGuidance).length === 0) return;
   const execute = stringField(usageGuidance, "execute");
   const toolExecutionResult = recordField(usageGuidance, "toolExecutionResult", "tool_execution_result");
-  const toolOutput = recordField(toolExecutionResult, "toolOutput", "tool_output");
-  const extractedLists = extractionEntries(toolExecutionResult, "extractedLists", "extracted_lists");
-  const extractedValues = extractionEntries(toolExecutionResult, "extractedValues", "extracted_values");
+  const toolResponse = recordField(toolExecutionResult, "toolResponse", "tool_response");
+  const extractedLists = arrayField(toolExecutionResult, "extractedLists", "extracted_lists");
+  const extractedValues = arrayField(toolExecutionResult, "extractedValues", "extracted_values");
   console.log("  Usage guidance:");
   if (execute) console.log(`    ${execute}`);
-  const raw = pathField(toolOutput, "raw");
-  const meta = pathField(toolOutput, "meta");
-  if (raw) console.log(`    Raw tool output: ${raw}`);
-  if (meta) console.log(`    Tool output metadata: ${meta}`);
+  const raw = stringField(toolResponse, "raw");
+  const meta = stringField(toolResponse, "meta");
+  if (raw) console.log(`    Raw tool response: ${raw}`);
+  if (meta) console.log(`    Tool response metadata: ${meta}`);
   printExtractions("Extracted lists", extractedLists);
   printExtractions("Extracted values", extractedValues);
 }
-function pathField(record, key) {
-  const value = record[key];
-  if (typeof value === "string") return value.trim();
-  if (isRecord3(value)) return stringField(value, "path");
-  return "";
-}
-function extractionEntries(record, camelKey, snakeKey) {
-  const value = record[camelKey] ?? record[snakeKey];
-  if (Array.isArray(value)) return value;
-  if (!isRecord3(value)) return [];
-  return Object.entries(value).map(
-    ([name, entry]) => isRecord3(entry) ? { name, ...entry } : { name }
-  );
-}
 function printExtractions(label, entries) {
   if (!entries.length) return;
   console.log(`    ${label}:`);
@@ -9561,7 +9583,7 @@ function listExtractorPathsFromUsageGuidance(tool) {
     const paths = entry.details?.candidatePaths ?? entry.details?.rawToolOutputPaths;
     if (!Array.isArray(paths)) return [];
     return paths.map(
-      (path) => path.trim().replace(/^toolExecutionResult\.toolOutput\.raw\.?/, "").replace(/^\./, "")
+      (path) => path.trim().replace(/^toolExecutionResult\.toolResponse\.raw\.?/, "").replace(/^toolExecutionResult\.toolOutput\.raw\.?/, "").replace(/^\./, "")
     ).filter(Boolean);
   });
 }
@@ -9633,12 +9655,11 @@ function normalizeOutputFormat(raw) {
 function parseExecuteOptions(args) {
   const toolId = args[0];
   if (!toolId) {
-    throw new Error(`Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--full-output] [--no-preview]`);
+    throw new Error(`Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--no-preview]`);
   }
   const params = {};
   let outputFormat = "auto";
   let noPreview = false;
-  let fullOutput = false;
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if ((arg === "--param" || arg === "-p") && args[index + 1]) {
@@ -9663,18 +9684,13 @@ function parseExecuteOptions(args) {
       outputFormat = normalizeOutputFormat(args[++index]);
       continue;
     }
-    if (arg === "--full-output") {
-      outputFormat = "json";
-      fullOutput = true;
-      continue;
-    }
     if (arg === "--no-preview") {
       noPreview = true;
       continue;
     }
     throw new Error(`Unknown option: ${arg}`);
   }
-  return { toolId, params, outputFormat, noPreview, fullOutput };
+  return { toolId, params, outputFormat, noPreview };
 }
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
@@ -9745,7 +9761,8 @@ function buildToolExecuteBaseEnvelope(input) {
     kind: summaryEntries.length > 0 ? "object" : "raw",
     summary: input.summary
   };
-  const envelopeHasCanonicalOutput = isRecord3(envelope.toolExecutionResult) && isRecord3(envelope.toolExecutionResult.toolOutput) && Object.prototype.hasOwnProperty.call(envelope.toolExecutionResult.toolOutput, "raw");
+  const envelopeHasCanonicalOutput = isRecord3(envelope.toolResponse) && Object.prototype.hasOwnProperty.call(envelope.toolResponse, "raw");
+  const inspectCommand = `deepline tools execute ${input.toolId} --input ${shellQuote(JSON.stringify(input.params))} --json`;
   const actions = input.listConversion ? [
     {
       label: "next",
@@ -9756,15 +9773,21 @@ function buildToolExecuteBaseEnvelope(input) {
     ...envelope,
     ...envelopeHasCanonicalOutput ? { output_preview: outputPreview } : { output: outputPreview },
     ...summaryEntries.length > 0 ? { summary: input.summary } : {},
-    next: input.listConversion ? {
-      expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
-    } : {},
+    next: {
+      inspect: inspectCommand,
+      playDebugging: "When fixing a play getter, inspect the actual play run table with runs get / inspect rows; do not copy CLI preview paths blindly.",
+      ...input.listConversion ? {
+        expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again.",
+        listSourcePath: input.listConversion.sourcePath ?? "auto-detected list in the CLI response preview"
+      } : {}
+    },
     render: {
       sections: input.listConversion ? [
         {
           title: "output",
           lines: [
             `${input.listConversion.rows.length} row(s) extracted from ${input.listConversion.sourcePath ?? "auto-detected list"}`,
+            "paths above are observed from this execute response; use run table rows to debug play getters",
             `columns: ${JSON.stringify(Object.keys(input.listConversion.rows[0] ?? {}))}`,
             `preview: ${JSON.stringify(input.listConversion.rows.slice(0, 5))}`
           ]
@@ -9807,16 +9830,13 @@ async function executeTool(args) {
     throw error;
   }
   const rawResponse = await client.executeTool(parsed.toolId, parsed.params);
-  if (parsed.fullOutput) {
-    printJson(rawResponse);
-    return 0;
-  }
   const listConversion = tryConvertToList(rawResponse, {
     listExtractorPaths: listExtractorPathsFromUsageGuidance(metadata)
   });
   const summary = extractSummaryFields(rawResponse);
   const baseEnvelope = buildToolExecuteBaseEnvelope({
     toolId: parsed.toolId,
+    params: parsed.params,
     rawResponse,
     listConversion,
     summary

package/dist/cli/index.mjs

@@ -193,8 +193,8 @@ function resolveConfig(options) {
 }
 
 // src/version.ts
-var SDK_VERSION = "0.1.35";
-var SDK_API_CONTRACT = "2026-05-v2-tool-result-contract";
+var SDK_VERSION = "0.1.36";
+var SDK_API_CONTRACT = "2026-05-v2-tool-response";
 
 // ../shared_libs/play-runtime/coordinator-headers.ts
 var COORDINATOR_INTERNAL_TOKEN_HEADER = "x-deepline-internal-token";
@@ -505,7 +505,7 @@ function sleep(ms) {
 var TERMINAL_PLAY_STATUSES = /* @__PURE__ */ new Set(["completed", "failed", "cancelled"]);
 var INCLUDE_TOOL_METADATA_HEADER = "x-deepline-include-tool-metadata";
 var EXECUTE_RESPONSE_CONTRACT_HEADER = "x-deepline-execute-response-contract";
-var V2_EXECUTE_RESPONSE_CONTRACT = "v2-tool-execution-result";
+var V2_EXECUTE_RESPONSE_CONTRACT = "v2-tool-response";
 var COMPILE_MANIFEST_RETRY_DELAYS_MS = [250, 1e3];
 function sleep2(ms) {
   return new Promise((resolve11) => setTimeout(resolve11, ms));
@@ -774,8 +774,8 @@ var DeeplineClient = class {
   /**
    * Execute a tool and return the standard execution envelope.
    *
-   * The `toolExecutionResult.toolOutput.raw` field contains the raw tool output.
-   * `toolExecutionResult.toolOutput.meta` contains tool/provider metadata.
+   * The `toolResponse.raw` field contains the raw tool response.
+   * `toolResponse.meta` contains tool/provider metadata.
    * Top-level fields such as `status`, `job_id`, and `billing` describe the
    * Deepline execution envelope.
    */
@@ -6574,6 +6574,7 @@ function buildRunNextCommands(status) {
   }
   const commands = {
     get: `deepline runs get ${runId} --json`,
+    full: `deepline runs get ${runId} --full --json`,
     stop: `deepline runs stop ${runId} --reason "stale lock" --json`,
     logs: `deepline runs logs ${runId} --out run.log --json`
   };
@@ -7268,6 +7269,10 @@ function renderServerResultView(value) {
     );
   }
   const tables = Array.isArray(view.tables) ? view.tables : [];
+  const topLevelOutputTable = view.topLevelOutputTable && typeof view.topLevelOutputTable === "object" && !Array.isArray(view.topLevelOutputTable) ? view.topLevelOutputTable : null;
+  if (typeof topLevelOutputTable?.queryCommand === "string") {
+    lines.push(`    top-level outputs: ${topLevelOutputTable.queryCommand}`);
+  }
   if (tables.length > 0) {
     lines.push("    tables:");
     for (const table of tables.slice(0, 6)) {
@@ -7284,6 +7289,21 @@ function renderServerResultView(value) {
       lines.push(
         `    ${String(table.tableNamespace ?? "table")}${lineLabel}: ${rowLabel}${details.join("  ")}`
       );
+      if (typeof table.queryDatasetCommand === "string") {
+        lines.push(`      inspect rows: ${table.queryDatasetCommand}`);
+      }
+      if (table.debugHelp && typeof table.debugHelp === "object" && !Array.isArray(table.debugHelp)) {
+        const debugHelp = table.debugHelp;
+        const rawResultFields = Array.isArray(debugHelp.rawResultFields) ? debugHelp.rawResultFields.filter(
+          (field) => typeof field === "string"
+        ) : [];
+        if (rawResultFields.length > 0) {
+          lines.push(`      tool-result columns: ${rawResultFields.join(", ")}`);
+        }
+      }
+      if (typeof table.slowExportAsCsvCommand === "string") {
+        lines.push(`      export rows: ${table.slowExportAsCsvCommand}`);
+      }
     }
   }
   return { lines: lines.length > 1 ? lines : [], actions: [] };
@@ -7309,7 +7329,8 @@ function writeStartedPlayRun(input) {
     `  get status: deepline runs get ${input.runId} --json`,
     `  logs: deepline runs logs ${input.runId} --json`,
     `  stop run: deepline runs stop ${input.runId} --reason "stale lock" --json`,
-    `  result JSON: deepline runs get ${input.runId} --json`
+    `  result JSON: deepline runs get ${input.runId} --json`,
+    `  full debug JSON: deepline runs get ${input.runId} --full --json`
   ];
   if (input.dashboardUrl) {
     lines.push(`  play page: ${input.dashboardUrl}`);
@@ -8947,17 +8968,13 @@ function normalizeRows(value) {
 }
 function candidateRoots(payload) {
   const roots = [{ path: null, value: payload }];
-  if (isPlainObject(payload) && isPlainObject(payload.toolExecutionResult)) {
-    roots.push({ path: "toolExecutionResult", value: payload.toolExecutionResult });
-    const toolOutput = payload.toolExecutionResult.toolOutput;
-    if (isPlainObject(toolOutput)) {
-      roots.push({ path: "toolExecutionResult.toolOutput", value: toolOutput });
-      if (Object.prototype.hasOwnProperty.call(toolOutput, "raw")) {
-        roots.push({
-          path: "toolExecutionResult.toolOutput.raw",
-          value: toolOutput.raw
-        });
-      }
+  if (isPlainObject(payload) && isPlainObject(payload.toolResponse)) {
+    roots.push({ path: "toolResponse", value: payload.toolResponse });
+    if (Object.prototype.hasOwnProperty.call(payload.toolResponse, "raw")) {
+      roots.push({
+        path: "toolResponse.raw",
+        value: payload.toolResponse.raw
+      });
     }
   }
   if (isPlainObject(payload) && isPlainObject(payload.output)) {
@@ -9263,7 +9280,7 @@ Notes:
   waterfalls, row maps, checkpoints, and retries.
   execute is the canonical execution verb. run is a compatibility alias.
   Calling a provider-backed tool can spend Deepline credits. Use --json for the
-  stable result payload and --full-output when debugging response metadata.
+  stable result payload plus output preview and debugging helpers.
 
 Examples:
   deepline tools execute hunter_email_verifier --input '{"email":"a@b.com"}'
@@ -9276,7 +9293,7 @@ Examples:
   }, []).option("--json [payload]", "Emit JSON output. Use `--input` or `--payload` for passing JSON params.").option("--input <payload>", "Merge a JSON object into the tool params").option("--payload <payload>", "Merge a JSON object into the tool params").option(
     "--output-format <format>",
     "Output format: auto, csv, csv_file, json, or json_file"
-  ).option("--full-output", "Emit the full JSON payload").option("--no-preview", "Only print the extracted output path when applicable").action(async (toolId, options) => {
+  ).option("--no-preview", "Only print the extracted output path when applicable").action(async (toolId, options) => {
     const args = [
       toolId,
       ...options.param.flatMap((value) => ["--param", value]),
@@ -9285,7 +9302,6 @@ Examples:
       ...options.input ? ["--input", options.input] : [],
       ...options.payload ? ["--payload", options.payload] : [],
       ...options.outputFormat ? ["--output-format", options.outputFormat] : [],
-      ...options.fullOutput ? ["--full-output"] : [],
       ...options.preview === false ? ["--no-preview"] : []
     ];
     process.exitCode = await executeTool(args);
@@ -9310,13 +9326,29 @@ async function getTool(args) {
     throw error;
   }
   if (argsWantJson(args)) {
-    process.stdout.write(`${JSON.stringify(tool)}
+    process.stdout.write(`${JSON.stringify(toolMetadataJsonForDescribe(tool, toolId))}
 `);
     return 0;
   }
   printToolDetails(tool, toolId);
   return 0;
 }
+function toolMetadataJsonForDescribe(tool, requestedToolId) {
+  const toolId = String(tool.toolId || requestedToolId);
+  return {
+    ...tool,
+    toolId,
+    provider: tool.provider,
+    displayName: tool.displayName,
+    runtimeOutputHelp: {
+      contract: "tools describe shows the declared schema and semantic getters; it is not an observed provider response.",
+      observeActualShape: `deepline tools execute ${toolId} --input '{...}' --json`,
+      observedOutput: `deepline tools execute ${toolId} --input '{...}' --json`,
+      forPlayGetterBugs: "Run the play, then inspect the emitted table commands from runs get. Use deepline db query against the run tables before editing getters.",
+      executeOutputFields: "tools execute JSON may include output_preview for this direct probe only; play debugging uses run tables."
+    }
+  };
+}
 function printToolDetails(tool, requestedToolId) {
   const toolId = String(tool.toolId || requestedToolId);
   const operation = typeof tool.operation === "string" ? tool.operation : "";
@@ -9337,6 +9369,10 @@ function printToolDetails(tool, requestedToolId) {
   const samples = recordField(tool, "samples");
   const usageGuidance = recordField(tool, "usageGuidance", "usage_guidance");
   console.log(`Tool: ${toolId}`);
+  console.log("  Runtime output help:");
+  console.log("    describe shows declared schema/getters, not an observed provider response");
+  console.log(`    observe actual shape: deepline tools execute ${toolId} --input '{...}' --json`);
+  console.log("    for play getter bugs: run the play, then use the db query commands printed by runs get");
   if (displayName) {
     console.log("  Display name:");
     console.log(`    ${displayName}`);
@@ -9433,32 +9469,18 @@ function printUsageGuidance(usageGuidance) {
   if (Object.keys(usageGuidance).length === 0) return;
   const execute = stringField(usageGuidance, "execute");
   const toolExecutionResult = recordField(usageGuidance, "toolExecutionResult", "tool_execution_result");
-  const toolOutput = recordField(toolExecutionResult, "toolOutput", "tool_output");
-  const extractedLists = extractionEntries(toolExecutionResult, "extractedLists", "extracted_lists");
-  const extractedValues = extractionEntries(toolExecutionResult, "extractedValues", "extracted_values");
+  const toolResponse = recordField(toolExecutionResult, "toolResponse", "tool_response");
+  const extractedLists = arrayField(toolExecutionResult, "extractedLists", "extracted_lists");
+  const extractedValues = arrayField(toolExecutionResult, "extractedValues", "extracted_values");
   console.log("  Usage guidance:");
   if (execute) console.log(`    ${execute}`);
-  const raw = pathField(toolOutput, "raw");
-  const meta = pathField(toolOutput, "meta");
-  if (raw) console.log(`    Raw tool output: ${raw}`);
-  if (meta) console.log(`    Tool output metadata: ${meta}`);
+  const raw = stringField(toolResponse, "raw");
+  const meta = stringField(toolResponse, "meta");
+  if (raw) console.log(`    Raw tool response: ${raw}`);
+  if (meta) console.log(`    Tool response metadata: ${meta}`);
   printExtractions("Extracted lists", extractedLists);
   printExtractions("Extracted values", extractedValues);
 }
-function pathField(record, key) {
-  const value = record[key];
-  if (typeof value === "string") return value.trim();
-  if (isRecord3(value)) return stringField(value, "path");
-  return "";
-}
-function extractionEntries(record, camelKey, snakeKey) {
-  const value = record[camelKey] ?? record[snakeKey];
-  if (Array.isArray(value)) return value;
-  if (!isRecord3(value)) return [];
-  return Object.entries(value).map(
-    ([name, entry]) => isRecord3(entry) ? { name, ...entry } : { name }
-  );
-}
 function printExtractions(label, entries) {
   if (!entries.length) return;
   console.log(`    ${label}:`);
@@ -9548,7 +9570,7 @@ function listExtractorPathsFromUsageGuidance(tool) {
     const paths = entry.details?.candidatePaths ?? entry.details?.rawToolOutputPaths;
     if (!Array.isArray(paths)) return [];
     return paths.map(
-      (path) => path.trim().replace(/^toolExecutionResult\.toolOutput\.raw\.?/, "").replace(/^\./, "")
+      (path) => path.trim().replace(/^toolExecutionResult\.toolResponse\.raw\.?/, "").replace(/^toolExecutionResult\.toolOutput\.raw\.?/, "").replace(/^\./, "")
     ).filter(Boolean);
   });
 }
@@ -9620,12 +9642,11 @@ function normalizeOutputFormat(raw) {
 function parseExecuteOptions(args) {
   const toolId = args[0];
   if (!toolId) {
-    throw new Error(`Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--full-output] [--no-preview]`);
+    throw new Error(`Usage: deepline tools execute <toolId> [--param key=value ...] [--input '{"k":"v"}'] [--output-format auto|csv|csv_file|json|json_file] [--no-preview]`);
   }
   const params = {};
   let outputFormat = "auto";
   let noPreview = false;
-  let fullOutput = false;
   for (let index = 1; index < args.length; index += 1) {
     const arg = args[index];
     if ((arg === "--param" || arg === "-p") && args[index + 1]) {
@@ -9650,18 +9671,13 @@ function parseExecuteOptions(args) {
       outputFormat = normalizeOutputFormat(args[++index]);
       continue;
     }
-    if (arg === "--full-output") {
-      outputFormat = "json";
-      fullOutput = true;
-      continue;
-    }
     if (arg === "--no-preview") {
       noPreview = true;
       continue;
     }
     throw new Error(`Unknown option: ${arg}`);
   }
-  return { toolId, params, outputFormat, noPreview, fullOutput };
+  return { toolId, params, outputFormat, noPreview };
 }
 function safeFileStem(value) {
   return value.trim().replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64) || "tool";
@@ -9732,7 +9748,8 @@ function buildToolExecuteBaseEnvelope(input) {
     kind: summaryEntries.length > 0 ? "object" : "raw",
     summary: input.summary
   };
-  const envelopeHasCanonicalOutput = isRecord3(envelope.toolExecutionResult) && isRecord3(envelope.toolExecutionResult.toolOutput) && Object.prototype.hasOwnProperty.call(envelope.toolExecutionResult.toolOutput, "raw");
+  const envelopeHasCanonicalOutput = isRecord3(envelope.toolResponse) && Object.prototype.hasOwnProperty.call(envelope.toolResponse, "raw");
+  const inspectCommand = `deepline tools execute ${input.toolId} --input ${shellQuote(JSON.stringify(input.params))} --json`;
   const actions = input.listConversion ? [
     {
       label: "next",
@@ -9743,15 +9760,21 @@ function buildToolExecuteBaseEnvelope(input) {
     ...envelope,
     ...envelopeHasCanonicalOutput ? { output_preview: outputPreview } : { output: outputPreview },
     ...summaryEntries.length > 0 ? { summary: input.summary } : {},
-    next: input.listConversion ? {
-      expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again."
-    } : {},
+    next: {
+      inspect: inspectCommand,
+      playDebugging: "When fixing a play getter, inspect the actual play run table with runs get / inspect rows; do not copy CLI preview paths blindly.",
+      ...input.listConversion ? {
+        expandToPlay: "Use stable map and step keys so reruns are idempotent: completed rows are reused, and only missing or stale work runs again.",
+        listSourcePath: input.listConversion.sourcePath ?? "auto-detected list in the CLI response preview"
+      } : {}
+    },
     render: {
       sections: input.listConversion ? [
         {
           title: "output",
           lines: [
             `${input.listConversion.rows.length} row(s) extracted from ${input.listConversion.sourcePath ?? "auto-detected list"}`,
+            "paths above are observed from this execute response; use run table rows to debug play getters",
             `columns: ${JSON.stringify(Object.keys(input.listConversion.rows[0] ?? {}))}`,
             `preview: ${JSON.stringify(input.listConversion.rows.slice(0, 5))}`
           ]
@@ -9794,16 +9817,13 @@ async function executeTool(args) {
     throw error;
   }
   const rawResponse = await client.executeTool(parsed.toolId, parsed.params);
-  if (parsed.fullOutput) {
-    printJson(rawResponse);
-    return 0;
-  }
   const listConversion = tryConvertToList(rawResponse, {
     listExtractorPaths: listExtractorPathsFromUsageGuidance(metadata)
   });
   const summary = extractSummaryFields(rawResponse);
   const baseEnvelope = buildToolExecuteBaseEnvelope({
     toolId: parsed.toolId,
+    params: parsed.params,
     rawResponse,
     listConversion,
     summary