fix: enforce required fields in agent output schemas (#638)

Remove .optional() and .default() from search_events and search_issues
agent output schemas. OpenAI's structured outputs require all properties
in the 'required' array, but Zod's .optional() and .default() break
this.

Changes:
- Use z.nullable() instead of .optional()/.nullish() for optional fields
- Add runtime validation in callEmbeddedAgent to catch missing fields
- Update tests to expect UserInputError on schema validation failures
- Add agent-output-schema.test.ts to verify all fields are required

Co-authored-by: Claude <[email protected]>

Author: dcramer

packages/mcp-server/src/internal/agents/callEmbeddedAgent.ts

@@ -1,5 +1,6 @@
 import { generateText, Output, type Tool } from "ai";
 import { getOpenAIModel } from "./openai-provider";
+import { UserInputError } from "../../errors";
 import type { z } from "zod";
 
 export type ToolCall = {
@@ -20,7 +21,10 @@ interface EmbeddedAgentResult<T> {
  * - Errors are re-thrown for the calling agent to handle
  * - Each agent can implement its own error handling strategy
  */
-export async function callEmbeddedAgent<T>({
+export async function callEmbeddedAgent<
+  TOutput,
+  TSchema extends z.ZodType<TOutput, z.ZodTypeDef, unknown>,
+>({
   system,
   prompt,
   tools,
@@ -29,8 +33,8 @@ export async function callEmbeddedAgent<T>({
   system: string;
   prompt: string;
   tools: Record<string, Tool>;
-  schema: z.ZodSchema<T>;
-}): Promise<EmbeddedAgentResult<T>> {
+  schema: TSchema;
+}): Promise<EmbeddedAgentResult<TOutput>> {
   const capturedToolCalls: ToolCall[] = [];
 
   const result = await generateText({
@@ -57,8 +61,27 @@ export async function callEmbeddedAgent<T>({
     throw new Error("Failed to generate output");
   }
 
+  const rawOutput = result.experimental_output;
+
+  if (
+    typeof rawOutput === "object" &&
+    rawOutput !== null &&
+    "error" in rawOutput &&
+    typeof (rawOutput as { error?: unknown }).error === "string"
+  ) {
+    throw new UserInputError((rawOutput as { error: string }).error);
+  }
+
+  const parsedResult = schema.safeParse(rawOutput);
+
+  if (!parsedResult.success) {
+    throw new UserInputError(
+      `Invalid agent response: ${parsedResult.error.message}`,
+    );
+  }
+
   return {
-    result: result.experimental_output as T,
+    result: parsedResult.data,
     toolCalls: capturedToolCalls,
   };
 }

packages/mcp-server/src/tools/agent-output-schema.test.ts

@@ -0,0 +1,45 @@
+import { describe, it } from "vitest";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import type { ZodTypeAny } from "zod";
+import { searchEventsAgentOutputSchema } from "./search-events/agent";
+import { searchIssuesAgentOutputSchema } from "./search-issues/agent";
+
+describe("agent output schemas", () => {
+  function expectRequiredFields(
+    name: string,
+    schema: ZodTypeAny,
+    expected: string[],
+  ) {
+    const jsonSchema = zodToJsonSchema(schema, {
+      $refStrategy: "none",
+    }) as { required?: string[] };
+    const required = jsonSchema.required ?? [];
+    const missing = expected.filter((field) => !required.includes(field));
+    const unexpected = required.filter((field) => !expected.includes(field));
+
+    if (missing.length || unexpected.length) {
+      throw new Error(
+        `${name} schema mismatch. Missing: ${missing.join(", ") || "none"}. Unexpected: ${unexpected.join(", ") || "none"}. Required fields: ${required.join(", ")}`,
+      );
+    }
+  }
+
+  it("marks all search_events fields as required", () => {
+    expectRequiredFields("search_events", searchEventsAgentOutputSchema, [
+      "dataset",
+      "query",
+      "fields",
+      "sort",
+      "timeRange",
+      "explanation",
+    ]);
+  });
+
+  it("marks all search_issues fields as required", () => {
+    expectRequiredFields("search_issues", searchIssuesAgentOutputSchema, [
+      "query",
+      "sort",
+      "explanation",
+    ]);
+  });
+});

packages/mcp-server/src/tools/search-events.test.ts

@@ -58,7 +58,8 @@ describe("search_events", () => {
           query,
           fields: fields || defaultFields[dataset],
           sort: sort || defaultSorts[dataset],
-          ...(timeRange && { timeRange }),
+          timeRange: timeRange ?? null,
+          explanation: "Test query translation",
         };
 
     return {
@@ -240,23 +241,24 @@ describe("search_events", () => {
       mockAIResponse("errors", "", [], "Cannot parse this query"),
     );
 
-    await expect(
-      searchEvents.handler(
-        {
-          organizationSlug: "test-org",
-          naturalLanguageQuery: "some impossible query !@#$%",
-          limit: 10,
-          includeExplanation: false,
-        },
-        {
-          constraints: {
-            organizationSlug: null,
-          },
-          accessToken: "test-token",
-          userId: "1",
+    const promise = searchEvents.handler(
+      {
+        organizationSlug: "test-org",
+        naturalLanguageQuery: "some impossible query !@#$%",
+        limit: 10,
+        includeExplanation: false,
+      },
+      {
+        constraints: {
+          organizationSlug: null,
         },
-      ),
-    ).rejects.toThrow(UserInputError);
+        accessToken: "test-token",
+        userId: "1",
+      },
+    );
+
+    await expect(promise).rejects.toThrow(UserInputError);
+    await expect(promise).rejects.toThrow("Cannot parse this query");
   });
 
   it("should return UserInputError for time series queries", async () => {
@@ -331,7 +333,7 @@ describe("search_events", () => {
   });
 
   it("should handle missing sort parameter", async () => {
-    // Mock AI response missing sort parameter
+    // Mock AI response missing sort parameter - schema.parse() will catch this
     mockGenerateText.mockResolvedValueOnce({
       text: JSON.stringify({
         dataset: "errors",
@@ -342,6 +344,7 @@ describe("search_events", () => {
         dataset: "errors",
         query: "test",
         fields: ["title"],
+        timeRange: null,
       },
     } as any);
 
@@ -361,7 +364,7 @@ describe("search_events", () => {
           userId: "1",
         },
       ),
-    ).rejects.toThrow("missing required 'sort' parameter");
+    ).rejects.toThrow(UserInputError);
   });
 
   it("should handle agent self-correction when sort field not in fields array", async () => {
@@ -379,6 +382,7 @@ describe("search_events", () => {
         query: "test",
         fields: ["title", "timestamp"],
         sort: "-timestamp",
+        timeRange: null,
         explanation: "Self-corrected to include sort field in fields array",
       },
     } as any);

packages/mcp-server/src/tools/search-events/agent.ts

@@ -7,16 +7,15 @@ import { createWhoamiTool } from "../../internal/agents/tools/whoami";
 import { createDatasetAttributesTool } from "./utils";
 import { systemPrompt } from "./config";
 
-const outputSchema = z
+// OpenAI structured outputs (used by GPT-5) require all properties to be in the 'required' array.
+// Avoid .optional()/.default() so the generated JSON Schema keeps every field required.
+// Tracking: https://github.com/getsentry/sentry-mcp/issues/623
+export const searchEventsAgentOutputSchema = z
   .object({
     dataset: z
       .enum(["spans", "errors", "logs"])
       .describe("Which dataset to use for the query"),
-    query: z
-      .string()
-      .default("")
-      .nullish()
-      .describe("The Sentry query string for filtering results"),
+    query: z.string().describe("The Sentry query string for filtering results"),
     fields: z
       .array(z.string())
       .describe("Array of field names to return in results."),
@@ -32,8 +31,8 @@ const outputSchema = z
           start: z.string().describe("ISO 8601 start time"),
           end: z.string().describe("ISO 8601 end time"),
         }),
+        z.null(),
       ])
-      .nullish()
       .describe(
         "Time range for filtering events. Use either statsPeriod for relative time or start/end for absolute time.",
       ),
@@ -76,7 +75,7 @@ export interface SearchEventsAgentOptions {
 export async function searchEventsAgent(
   options: SearchEventsAgentOptions,
 ): Promise<{
-  result: z.infer<typeof outputSchema>;
+  result: z.output<typeof searchEventsAgentOutputSchema>;
   toolCalls: any[];
 }> {
   if (!process.env.OPENAI_API_KEY) {
@@ -99,14 +98,17 @@ export async function searchEventsAgent(
   const whoamiTool = createWhoamiTool({ apiService: options.apiService });
 
   // Use callEmbeddedAgent to translate the query with tool call capture
-  return await callEmbeddedAgent({
+  return await callEmbeddedAgent<
+    z.output<typeof searchEventsAgentOutputSchema>,
+    typeof searchEventsAgentOutputSchema
+  >({
     system: systemPrompt,
     prompt: options.query,
     tools: {
       datasetAttributes: datasetAttributesTool,
       otelSemantics: otelLookupTool,
       whoami: whoamiTool,
     },
-    schema: outputSchema,
+    schema: searchEventsAgentOutputSchema,
   });
 }

packages/mcp-server/src/tools/search-events/handler.ts

@@ -115,8 +115,8 @@ export default defineTool({
 
     const parsed = agentResult.result;
 
-    // Get the dataset chosen by the agent (should be defined when no error)
-    const dataset = parsed.dataset!;
+    // Get the dataset chosen by the agent
+    const dataset = parsed.dataset;
 
     // Get recommended fields for this dataset (for fallback when no fields are provided)
     const recommendedFields = RECOMMENDED_FIELDS[dataset];

packages/mcp-server/src/tools/search-issues/agent.ts

@@ -6,16 +6,14 @@ import { createDatasetFieldsTool } from "../../internal/agents/tools/dataset-fie
 import { createWhoamiTool } from "../../internal/agents/tools/whoami";
 import { systemPrompt } from "./config";
 
-const outputSchema = z.object({
-  query: z
-    .string()
-    .default("")
-    .nullish()
-    .describe("The Sentry issue search query"),
+// OpenAI structured outputs (used by GPT-5) require all properties to be in the 'required' array.
+// Avoid .optional()/.default() so the generated JSON Schema keeps every field required.
+// Tracking: https://github.com/getsentry/sentry-mcp/issues/623
+export const searchIssuesAgentOutputSchema = z.object({
+  query: z.string().describe("The Sentry issue search query"),
   sort: z
     .enum(["date", "freq", "new", "user"])
-    .default("date")
-    .nullish()
+    .nullable()
     .describe("How to sort the results"),
   explanation: z
     .string()
@@ -36,7 +34,7 @@ export interface SearchIssuesAgentOptions {
 export async function searchIssuesAgent(
   options: SearchIssuesAgentOptions,
 ): Promise<{
-  result: z.infer<typeof outputSchema>;
+  result: z.output<typeof searchIssuesAgentOutputSchema>;
   toolCalls: any[];
 }> {
   if (!process.env.OPENAI_API_KEY) {
@@ -46,7 +44,10 @@ export async function searchIssuesAgent(
   }
 
   // Create tools pre-bound with the provided API service and organization
-  return await callEmbeddedAgent({
+  return await callEmbeddedAgent<
+    z.output<typeof searchIssuesAgentOutputSchema>,
+    typeof searchIssuesAgentOutputSchema
+  >({
     system: systemPrompt,
     prompt: options.query,
     tools: {
@@ -58,6 +59,6 @@ export async function searchIssuesAgent(
       }),
       whoami: createWhoamiTool({ apiService: options.apiService }),
     },
-    schema: outputSchema,
+    schema: searchIssuesAgentOutputSchema,
   });
 }

packages/mcp-test-client/src/mcp-test-client.ts

@@ -25,10 +25,7 @@ export async function connectToMCPServer(
       },
       async (span) => {
         try {
-          const args = [
-            `--access-token=${config.accessToken}`,
-            "--all-scopes", // Ensure all tools are available in local stdio runs
-          ];
+          const args = [`--access-token=${config.accessToken}`];
           if (config.host) {
             args.push(`--host=${config.host}`);
           }