_runheed
Sign in

MCP error -32602: Input validation error: Invalid arguments for tool get_order

Node.js · updated 2026-11-11

Returned by the MCP TypeScript SDK when a tools/call doesn't match the server: the arguments fail the tool's zod inputSchema, or no tool has that name. SDK 1.x sends it back as a tool result with isError: true and text such as "MCP error -32602: Input validation error: Invalid arguments for tool get_order: Invalid UUID at orderId", or "MCP error -32602: Tool nope not found". The v2 server package returns the same validation text without the prefix, and the v2 client throws ProtocolError -32602 for an unknown tool. The agent sees it and usually retries; your handler never runs.

{
  "content": [{
    "type": "text",
    "text": "MCP error -32602: Input validation error: Invalid arguments for tool get_order: Invalid UUID at orderId\nToo big: expected number to be <=50 at limit"
  }],
  "isError": true
}

Quick fix

Read the field names after "at" (or before the colon in v2): they say exactly which argument failed and why. If agents keep sending the wrong shape, the fix is usually in the schema and the description, not the agent: make the constraint visible in .describe() text, loosen limits the agent can't know (exact ID formats, small maximums), or coerce types the agent sends as strings.

  1. Find the failing field and rule in the message (for example "Invalid UUID at orderId" or "expected number to be <=50 at limit").
  2. Add .describe() to every parameter with the format and range, so the client shows it to the model.
  3. Accept what agents commonly send: z.coerce.number() for numbers sent as strings, a larger max with clamping inside the handler.
  4. For "Tool X not found", check the tool name the client cached; reconnect after renaming or removing tools.
  5. Log rejected calls on the server if you need to see them: the SDK answers before your handler, so nothing in your code fires.
typescript
import { z } from 'zod';

server.registerTool(
  'get_order',
  {
    description: 'Returns one order by its ID.',
    inputSchema: {
      orderId: z.string().uuid().describe('Order ID, a UUID such as 3f6c1e2a-...'),
      // Agents often send "100" or ask for more than you allow: coerce and clamp
      limit: z.coerce.number().int().min(1).max(500).default(20)
        .describe('Max line items to return, 1 to 500'),
    },
  },
  async ({ orderId, limit }) => {
    const items = await loadItems(orderId, Math.min(limit, 50));
    return { content: [{ type: 'text', text: JSON.stringify(items) }] };
  },
);
Fix it with your coding agent

Paste this into Claude Code, Cursor or Codex in the project that throws it. The agent reads this guide in plain text and applies the fix that matches your stack.

prompttext
Read https://runheed.com/errors/mcp-error-32602-invalid-params.md and fix this error in this project.

Why it happens

The schema is stricter than its description

A uuid(), regex or max() the model can't see in the description gets violated on the first try.

Wrong types from the model

Numbers and booleans sent as strings, or an object where the schema wants an array.

Missing required arguments

A field the model doesn't know it needs, often an ID it should have fetched with another tool first.

Stale tool list

The client cached tools/list before a rename or removal, so it calls a tool that no longer exists ("Tool X not found").

Other fixes

  • A malformed request (arguments that are not an object at all) fails earlier with -32603 instead.
  • If you validate inside the handler yourself, return an isError result with a plain message so the model can correct the call.

Same error, other wording

  • MCP error -32602: Tool get_order not found
  • Input validation error: Invalid arguments for tool get_order: orderId: Invalid UUID (SDK v2)
  • ProtocolError: Tool get_order not found (code -32602, SDK v2)
  • MCP error -32602: Invalid params

Let your coding agent catch the next one

The MCP SDK answers the call with this error itself and your tool code never runs, so Runheed doesn't record it. What it does record is the exceptions your running server code throws (route handlers, server rendering, API errors and background jobs) with the stack trace and the breadcrumbs before them, and serves those errors to Claude Code, Cursor or any MCP client.

7-day trial, then $29/moTry it in your agent on sample errorsSee the setupCancel any time from the billing portal

Setup for Node.js and Express or Vercel Functions, then have your agent fix and resolve it.

Building an MCP server? Track the errors your tools raise, in TypeScript or Python, so a failing tool shows up with its line instead of only in your users' client logs.

Related errors

More in MCP servers and clients

References: MCP specification: tools (calling tools, error handling), JSON-RPC 2.0 specification: error codes (-32602 Invalid params), MCP TypeScript SDK repository

Spotted a mistake? Email hello@greatwork.company. About Runheed.