ToolCallFilter

The ToolCallFilter is an input processor that filters out tool calls and their results from the message history before sending to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.

Usage example

import { ToolCallFilter } from '@mastra/core/processors'

// Exclude all tool calls
const filterAll = new ToolCallFilter()

// Exclude specific tools by name
const filterSpecific = new ToolCallFilter({
  exclude: ['searchDatabase', 'sendEmail'],
})

// Enable filtering during agent loops and keep the two most recent tool-producing steps
const filterAfterRecentTools = new ToolCallFilter({
  filterAfterToolSteps: 2,
})

// Preserve compact model-facing output for filtered completed tool results
const filterWithCompactToolHistory = new ToolCallFilter({
  preserveModelOutput: true,
})

Constructor parameters

options?:

Options

Configuration options for the tool call filter

Options

exclude?:

string[]

List of specific tool names to exclude. If not provided or undefined, all tool calls are excluded

filterAfterToolSteps?:

number

Enables filtering during agent loops and preserves tool calls and results from this many recent tool-producing steps. If undefined, step filtering is disabled

preserveModelOutput?:

boolean

Preserves compact model-facing output from completed filtered tool results with providerMetadata.mastra.modelOutput. Raw tool args and raw results are removed

Returns

id:

string

Processor identifier set to 'tool-call-filter'

name:

string

Processor display name set to 'ToolCallFilter'

processInput:

(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>

Processes input messages to filter out tool calls and their results based on configuration

processInputStep:

(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>

Processes agent loop step input when filterAfterToolSteps is configured. Returns no changes when step filtering is disabled

Step filtering

By default, ToolCallFilter filters only the initial input before the agent loop starts. Set filterAfterToolSteps to also filter during each loop step.

filterAfterToolSteps counts tool-producing steps. For example, filterAfterToolSteps: 2 keeps tool calls and results from the two most recent tool-producing steps and filters older tool calls and results. Non-tool text remains in context.

Set filterAfterToolSteps: 0 to filter all previous tool calls and results on each step.

const filter = new ToolCallFilter({
  filterAfterToolSteps: 2,
})

Preserve compact model output

Set preserveModelOutput: true to retain compact toModelOutput history for completed tool results that the filter removes. This keeps the model-facing output as text in the prompt while removing the raw toolInvocation.args and raw toolInvocation.result payloads.

Only completed tool results with providerMetadata.mastra.modelOutput are preserved. Tool calls, incomplete results, and results without stored model output are still filtered.

const filter = new ToolCallFilter({
  preserveModelOutput: true,
})

Combine preserveModelOutput with exclude to preserve compact output only for filtered tools:

const filter = new ToolCallFilter({
  exclude: ['searchDatabase'],
  preserveModelOutput: true,
})

Extended usage example

src/mastra/agents/filtered-agent.ts

import { Agent } from '@mastra/core/agent'
import { ToolCallFilter } from '@mastra/core/processors'

export const agent = new Agent({
  name: 'filtered-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.4',
  tools: {
    searchDatabase,
    sendEmail,
    getWeather,
  },
  inputProcessors: [
    // Filter out database search tool calls from context
    // to reduce token usage while keeping other tool interactions
    new ToolCallFilter({
      exclude: ['searchDatabase'],
    }),
  ],
})

Filtering all tool calls

import { Agent } from '@mastra/core/agent'
import { ToolCallFilter } from '@mastra/core/processors'

export const agent = new Agent({
  name: 'no-tools-context-agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.4',
  tools: {
    searchDatabase,
    sendEmail,
  },
  inputProcessors: [
    // Remove all tool calls from the message history
    // The agent can still use tools, but previous tool interactions
    // won't be included in the context
    new ToolCallFilter(),
  ],
})

Related

• Guardrails