addToolInputExamplesMiddleware

addToolInputExamplesMiddleware is a middleware function that appends input examples to tool descriptions. This is especially useful for language model providers that do not natively support the inputExamples property—the middleware serializes and injects the examples into the tool's description so models can learn from them.

Import

<Snippet text={import { addToolInputExamplesMiddleware } from "ai"} prompt={false} />

API

Signature

function addToolInputExamplesMiddleware(options?: {
  prefix?: string;
  format?: (example: { input: JSONObject }, index: number) => string;
  remove?: boolean;
}): LanguageModelMiddleware;

Parameters

<PropertiesTable content={[ { name: 'prefix', type: 'string', isOptional: true, description: "A prefix prepended before the input examples section. Defaults to 'Input Examples:'.", }, { name: 'format', type: '(example: { input: JSONObject }, index: number) => string', isOptional: true, description: 'Optional custom formatter for each example. Receives the example object and its index. Default: JSON.stringify(example.input).', }, { name: 'remove', type: 'boolean', isOptional: true, description: 'Whether to remove the inputExamples property from the tool after adding them to the description. Default: true.', }, ]} />

Returns

A LanguageModelMiddleware that:

• Locates function tools with an inputExamples property.
• Serializes each input example (by default as JSON, or using your custom formatter).
• Prepends a section at the end of the tool description containing all formatted examples, prefixed by the prefix.
• Removes the inputExamples property from the tool (unless remove: false).
• Passes through all other tools (including those without examples) unchanged.

Usage Example

import {
  generateText,
  tool,
  wrapLanguageModel,
  addToolInputExamplesMiddleware,
} from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';

const model = wrapLanguageModel({
  model: __MODEL__,
  middleware: addToolInputExamplesMiddleware({
    prefix: 'Input Examples:',
    format: (example, index) =>
      `${index + 1}. ${JSON.stringify(example.input)}`,
  }),
});

const result = await generateText({
  model,
  tools: {
    weather: tool({
      description: 'Get the weather in a location',
      inputSchema: z.object({ location: z.string() }),
      inputExamples: [
        { input: { location: 'San Francisco' } },
        { input: { location: 'London' } },
      ],
    }),
  },
  prompt: 'What is the weather in Tokyo?',
});

How It Works

1. For every function tool that defines inputExamples, the middleware:

   • Formats each example with the format function (default: JSON.stringify).

   • Builds a section like:

     Copy

     Input Examples:
     {"location":"San Francisco"}
     {"location":"London"}
     

   • Appends this section to the end of the tool's description.

2. By default, it removes the inputExamples property after appending to prevent duplication (can be disabled with remove: false).

3. Tools without input examples or non-function tools are left unmodified.

Tip: This middleware is especially useful with providers such as OpenAI or Anthropic, where native support for inputExamples is not available.

Example effect

If your original tool definition is:

{
  type: 'function',
  name: 'weather',
  description: 'Get the weather in a location',
  inputSchema: { ... },
  inputExamples: [
    { input: { location: 'San Francisco' } },
    { input: { location: 'London' } }
  ]
}

After applying the middleware (with default settings), the tool passed to the model will look like:

{
  type: 'function',
  name: 'weather',
  description: `Get the weather in a location

Input Examples:
{"location":"San Francisco"}
{"location":"London"}`,
  inputSchema: { ... }
  // inputExamples is removed by default
}