Improvements for set_output tool prompt/params parsing

Author: jahooma

common/src/tools/params/tool/set-output.ts

@@ -6,6 +6,21 @@ import type { $ToolParams } from '../../constants'
 
 const toolName = 'set_output'
 const endsAgentStep = false
+
+// WHY `data` EXISTS IN THE INPUT SCHEMA:
+// Subagents inherit their parent's tool definitions, and because of prompt caching
+// we cannot modify or add tools mid-conversation. OpenAI models enforce the tool's
+// input schema strictly, so we need a permissive shape that any model can call.
+// An empty schema or `z.object({}).passthrough()` would be rejected by OpenAI's
+// strict schema enforcement. The `data: z.record(...)` field is a deliberately
+// vague shape that satisfies OpenAI while allowing us to inject the real
+// outputSchema later in the conversation (in the instructions prompt).
+//
+// At runtime, the handler (`packages/agent-runtime/src/tools/handlers/tool/set-output.ts`)
+// tries parsing against the real outputSchema in two ways:
+//   1. Parse the raw output (agent passed fields at top level)
+//   2. Fallback: parse `output.data` (agent wrapped fields in `data`)
+// This means both `{ results: [...] }` and `{ data: { results: [...] } }` are accepted.
 const inputSchema = z
   .looseObject({
     data: z.record(z.string(), z.any()).optional(),

packages/agent-runtime/src/templates/strings.ts

@@ -226,7 +226,7 @@ export async function getAgentPrompt<T extends StringField>(
     if (outputSchema) {
       addendum += '\n\n## Output Schema\n\n'
       addendum +=
-        'When using the set_output tool, your output must conform to this schema:\n\n'
+        'When using the set_output tool, your output must conform to this schema. You may pass the fields either directly as top-level parameters or inside a `data` field — both are accepted.\n\n'
       addendum += '```json\n'
       try {
         // Convert Zod schema to JSON schema for display

packages/agent-runtime/src/tools/handlers/tool/set-output.ts

@@ -52,13 +52,24 @@ export const handleSetOutput = (async (params: {
         agentTemplate.outputSchema.parse(data)
         finalOutput = data
       } catch (error2) {
-        const errorMessage = `Output validation error: Output failed to match the output schema and was ignored. You might want to try again! Issues: ${error}`
+        // Show whichever error has fewer issues — that represents the "closer" parse
+        // attempt and gives the agent more actionable feedback for retrying.
+        const issues1 = getZodIssueCount(error)
+        const issues2 = getZodIssueCount(error2)
+        const usedData = issues2 < issues1
+        const bestError = usedData ? error2 : error
+        const prefix = usedData
+          ? 'Output validation error: Your output was found inside the `data` field but still failed validation. Please fix the issues and try again without wrapping in `data`. Issues: '
+          : 'Output validation error: Output failed to match the output schema and was ignored. You might want to try again! Issues: '
+        const errorMessage = `${prefix}${bestError}`
         logger.error(
           {
             output,
             agentType: agentState.agentType,
             agentId: agentState.agentId,
-            error,
+            topLevelError: error,
+            dataFieldError: error2,
+            usedDataFieldError: usedData,
           },
           'set_output validation error',
         )
@@ -78,3 +89,15 @@ export const handleSetOutput = (async (params: {
 
   return { output: jsonToolResult({ message: 'Output set' }) }
 }) satisfies CodebuffToolHandlerFunction<ToolName>
+
+function getZodIssueCount(error: unknown): number {
+  if (
+    error != null &&
+    typeof error === 'object' &&
+    'issues' in error &&
+    Array.isArray((error as { issues: unknown }).issues)
+  ) {
+    return (error as { issues: unknown[] }).issues.length
+  }
+  return Infinity
+}