mastra-ai/mastra · error

Tool parameters are required

Error message

Tool parameters are required

What it means

The v5 tool builder's buildV5() requires the built tool to have a parameters (input schema) object, which it maps to inputSchema. Tools without any input schema cannot be represented in the v5 tool contract, so CoreToolBuilder throws 'Tool parameters are required'.

Source

Thrown at packages/core/src/tools/tool-builder/builder.ts:927

              errorMessage: String(err),
              argsJson: safeStringify(args),
              model: model?.modelId ?? '',
            },
          },
          err,
        );
        toolSpan?.error({ error: mastraError, attributes: { success: false } });
        logger.trackException(mastraError, { ...logData, ...rest, model: logModelObject, args });
        throw mastraError;
      }
    };
  }

  buildV5() {
    const builtTool = this.build();

    if (!builtTool.parameters) {
      throw new Error('Tool parameters are required');
    }

    const base = {
      ...builtTool,
      inputSchema: builtTool.parameters,
      onInputStart: 'onInputStart' in this.originalTool ? this.originalTool.onInputStart : undefined,
      onInputDelta: 'onInputDelta' in this.originalTool ? this.originalTool.onInputDelta : undefined,
      onInputAvailable: 'onInputAvailable' in this.originalTool ? this.originalTool.onInputAvailable : undefined,
      onOutput: 'onOutput' in this.originalTool ? this.originalTool.onOutput : undefined,
    };

    // For provider-defined tools, exclude execute and add name as per v5 spec
    if (builtTool.type === 'provider-defined') {
      const { execute, parameters, ...rest } = base;
      // Prefer the preserved provider name (e.g. "web_search" from V5 SDK
      // factories) over the ID-derived name (e.g. "web_search_20250305").
      const name =
        ('name' in builtTool && typeof builtTool.name === 'string' ? builtTool.name : null) ||

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add an inputSchema to the tool definition, using z.object({}) for tools that take no input.
2. If the tool genuinely has no inputs, define parameters as an empty object schema rather than omitting it.
3. Check that your builder chain (inputSchema/parameters step) is not conditionally skipped.

Example fix

// before
createTool({ id: 'ping', execute: async () => 'pong' });
// after
import { z } from 'zod';
createTool({ id: 'ping', inputSchema: z.object({}), execute: async () => 'pong' });

import { z } from 'zod';
if (!toolDef.inputSchema) {
  toolDef.inputSchema = z.object({}); // zero-argument tools still need a schema
}

function hasInputSchema(t: { inputSchema?: unknown }): t is { inputSchema: object } {
  return t.inputSchema != null;
}

try {
  const built = builder.buildV5();
} catch (e) {
  if (String(e.message) === 'Tool parameters are required') {
    // add inputSchema: z.object({}) and rebuild
  } else throw e;
}

When it happens

Trigger: Calling createTool().buildV5() (or the v5 path via agent/tool conversion) on a tool defined with no inputSchema/parameters, e.g. createTool({ id, execute }) with the schema omitted.

Common situations: Migrating legacy tools that had optional schemas; defining zero-argument tools by simply omitting inputSchema instead of an empty-object schema; refactor that removed inputSchema assuming it was optional in v5.

Related errors

• ClaudeSDKAgent resumeData must include sessionId or continue
• CursorSDKAgent resumeData must include a message.
• CursorSDKAgent resumeData.agentId must be a string when prov
• CursorSDKAgent does not support structuredOutput because the
• OpenAISDKAgent resumeData must include a message.

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/1ba88da06de3ea84. Report an issue: GitHub.