Tool calling includes schema default values causing API validation errors

[rounakbende10]

Description

When using the Agents SDK for tool calling with MCP tools, schema default values are included in the tool call even when not explicitly set by the LLM. This causes API validation errors with services that reject invalid defaults.

Example

GitHub create_issue tool call includes:

{
  "owner": "user",
  "repo": "myrepo",
  "title": "New Issue",
  "milestone": 0,
  "assignees": [],
  "labels": []
}

GitHub API rejects milestone: 0 with 422 Unprocessable Entity because 0 is not a valid milestone ID (must be a positive integer or omitted entirely).

Expected Behavior

Tool calls should only include parameters explicitly set by the LLM, not schema defaults. Expected payload:

{
  "owner": "user",
  "repo": "myrepo",
  "title": "New Issue"
}

Workaround

Implemented input sanitization before passing to MCP tools:

function sanitizeToolInput(input: Record<string, unknown>): Record<string, unknown> {
  const sanitized: Record<string, unknown> = {};
  for (const [key, value] of Object.entries(input)) {
    // Skip invalid defaults
    if (value === 0 && key === "milestone") continue;
    if (Array.isArray(value) && value.length === 0) continue;
    if (value === null || value === undefined) continue;
    sanitized[key] = value;
  }
  return sanitized;
}

This removes milestone: 0, empty arrays, and null/undefined values before API calls.

Environment

• Agents SDK version: 0.3.6
• MCP SDK: @modelcontextprotocol/sdk
• Affected tools: GitHub MCP server (@modelcontextprotocol/server-github)

Additional Context

Discovered while comparing code generation (codemode) vs traditional tool calling. Code generation avoids this issue because the LLM explicitly writes only the parameters it needs in the generated code.

[mattzcarey]

I'm confused. The GitHub MCP Server sets defaults and you are proposing we strip them? Shouldn't this be an issue on the GitHub MCP Server.

[rounakbende10]

Good question. The issue is really about how the AI SDK handles schema defaults when calling tools.

So what's happening:

1. GitHub MCP Server defines optional fields like milestone (number) and labels (array)
2. When the LLM calls the tool, the AI SDK sends default values for these. So you get milestone: 0, labels: []
3. GitHub API rejects milestone: 0 because there's no milestone with ID 0

The schema itself is fine since these fields are optional. The problem is the SDK sending defaults for fields the LLM didn't ask for.

We worked around it by sanitizing inputs before the tool call. But ideally the SDK just wouldn't send these.

Raised it here since this affects any MCP tool with optional fields, not just GitHub.