MCP Tool Execution and Components

Choose a processor tool when the tool’s purpose is to compute or transform data, call an external API and return the response, or validate inputs and return errors or results.

Consider a scenario where an AI agent needs current weather data to answer a user’s question about whether to bring an umbrella.

The following prompts should trigger this type of tool:

A processor is the right choice because the tool fetches data from an API, transforms it into a useful format, and returns it.

Consider a scenario where an AI agent needs to validate user-submitted data and return structured feedback about any issues.

The following prompts should trigger this type of tool:

A processor is the right choice because the tool examines data, applies validation rules, and returns results. No data is written anywhere.

Choose an output tool when the tool’s purpose is to write data to Redpanda, a database, or an external API. The side effect (writing) should be the primary intent, not incidental. You can use processors: within the output to transform data before writing. Output tools are appropriate when you want the AI to trigger real-world actions.

Output tools have two outcomes: the side effect (data is written to the destination) and the tool response (the AI client receives confirmation that the write succeeded).

The AI client does not receive the written data back. It receives status information. If you need to return the written data, consider using a processor tool instead.

Consider a scenario where an AI agent needs to publish order events to Redpanda for downstream processing.

The following prompts should trigger this type of tool:

An output is the right choice because the purpose is to write data to Redpanda. The AI needs to create a persistent record, not just compute something.

Output components can include a processors: section that transforms data before writing to the destination. This is a single output component, not a combination of component types.

Consider a scenario where an AI agent asks an LLM to summarize a document, then stores both the original and summary in Redpanda.

The following prompts should trigger this type of tool:

An output with processors is the right choice because the primary intent is to store data. The processors provide pre-processing before writing.

The execution flow for this pattern is as follows:

For implementation examples, see outputs with processors in the tool patterns guide.

Choose an input tool when the tool’s purpose is to read and return data from an external source, consume messages from a Redpanda topic, or build a query-style tool that retrieves existing data.

Input tools must return a finite result. Use bounded reads that fetch a specific number of messages or read until a condition is met. For example, "get me the latest N events" or "read messages from the last hour". Unbounded reads that poll continuously are not appropriate for MCP tools because the tool would never return a response to the AI client.

Keep these factors in mind when building input tools:

Consider a scenario where an AI agent needs to retrieve recent user activity events to understand user behavior.

The following prompts should trigger this type of tool:

An input is the right choice because the tool reads from an existing data source (topic) and returns what it finds.

Choose a cache tool when the tool’s purpose is to store temporary data that expires after a set time, share state between multiple tool calls in a conversation, or reduce repeated calls to slow external APIs by caching results.

Consider a scenario where an AI agent needs to remember user preferences across multiple tool calls within a conversation.

The following prompts should trigger this type of tool:

A cache is the right choice because the data is temporary, session-scoped, and needs to be accessible by other tools during the conversation.

Consider a scenario where an AI agent frequently looks up the same reference data (like exchange rates or product catalogs) and you want to avoid repeated API calls.

The following prompts should trigger cache usage:

A cache is the right choice because you want to store API responses temporarily and serve them on subsequent requests without hitting the external API again.