@callback cache_control(arg()) :: {:public | :private, non_neg_integer()}

Returns the cache hint {scope, ttl_ms} for the tool, as {:public | :private, milliseconds}.

Optional. When implemented, the value is used as the tool's cache hint; otherwise the no-cache default from GenMCP.MCP.V2607.default_cache_control/0 applies. Use :public for results safe to share across clients and :private for per-caller results.

use GenMCP.Suite.Tool generates this callback from the :cache_control option, given as the {scope, ttl_ms} tuple itself:

use GenMCP.Suite.Tool,
  name: "list_countries",
  input_schema: %{},
  cache_control: {:public, :timer.minutes(5)}

Implement it by hand instead when the hint is computed from arg:

@impl true
def cache_control(_arg) do
  {:public, :timer.minutes(5)}
end

@callback call(GenMCP.MCP.V2607.CallToolRequest.t(), GenMCP.Mux.Channel.t(), arg()) ::
  call_result()

Runs the tool call and returns its result.

This is the one callback every tool implements. It receives the request (with arguments already validated by validate_request/2), the request-scoped channel, and the configured arg. Build the result with the GenMCP.MCP.V2607 helpers, most often GenMCP.MCP.V2607.call_tool_result/1.

Note the return tuples carry no channel: the channel is for sending interim output during the call, not for handing back.

@impl true
def call(request, _channel, _arg) do
  %{"city" => city} = request.params.arguments
  {:result, MCP.call_tool_result(text: "It is sunny in #{city}.")}
end

Return values

• {:result, result} answers the call. result is a GenMCP.MCP.V2607.CallToolResult.t/0, typically from GenMCP.MCP.V2607.call_tool_result/1. Pass error: message to that helper to return a tool-level error the model can read, as opposed to a protocol error.
• {:stream, state} keeps the worker alive as the request's streaming handler. state is carried to the next handle_message/4. See the "Streaming tools" section of the module doc.
• {:error, reason} fails the call with a protocol error. reason is a message string.
• {:input_required, requests, client_state} asks the client to satisfy one or more nested requests (sampling, roots, or elicitation) before retrying. requests is a map of request id to request struct, and client_state is node-portable plain data the Suite seals into the opaque requestState it returns, then hands back as request.params.requestState on the retry.

Returning a tool-level error from a successful call, rather than a protocol error, lets the client see the message:

def call(_request, _channel, _arg) do
  {:result, MCP.call_tool_result(error: "Upstream service unavailable")}
end

A tool that takes a long time before it can answer calls GenMCP.Mux.Channel.start_stream/1 first, so the transport keeps the connection alive while it works. See the "Slow tools" section of the module doc.

@callback handle_close(GenMCP.Mux.Channel.t(), state(), arg()) :: term()

Runs cleanup when the client disconnects during a streaming call.

Optional. Invoked when the client closes the connection while this tool is the active streaming handler (after call/3 returned {:stream, state}). The channel is already closed, so nothing more can be sent; state is the latest streaming state and arg the configured argument. The return value is ignored and the worker stops afterward, so use it only for side-effecting cleanup such as unsubscribing from your event source.

@impl true
def handle_close(_channel, _state, _arg) do
  :ok
end

@callback handle_message(term(), GenMCP.Mux.Channel.t(), state(), arg()) :: call_result()

Handles a process message delivered to a streaming tool.

Invoked once for every message the worker process receives after call/3 (or a previous handle_message/4) returned {:stream, state}. The message is whatever was sent to the worker, channel is the request-scoped channel, state is the term carried from the previous return, and arg is the configured argument. Returns the same shapes as call/3.

Match on the messages your tool subscribed to. The example below forwards a job result from the application's own queue and finishes the call:

@impl true
def handle_message({:job_finished, result}, _channel, _state, _arg) do
  {:result, MCP.call_tool_result(text: result)}
end

Return {:stream, new_state} instead to keep waiting, accumulating progress in new_state, and emit interim updates with GenMCP.Mux.Channel.send_progress/4:

def handle_message({:chunk, data}, channel, acc, _arg) do
  GenMCP.Mux.Channel.send_progress(channel, length(acc) + 1, nil, "received chunk")
  {:stream, [data | acc]}
end

def handle_message(:done, _channel, acc, _arg) do
  {:result, MCP.call_tool_result(text: Enum.join(Enum.reverse(acc)))}
end

@callback info(:name, arg()) :: String.t()

@callback info(:description, arg()) :: nil | String.t()

@callback info(:title, arg()) :: nil | String.t()

@callback info(:annotations, arg()) :: nil | tool_annotations()

@callback info(:_meta, arg()) :: nil | map()

Returns the tool metadata for the given key.

The Suite calls this once per metadata field to build the tools/list entry. :name must return a non-blank string; the other keys may return nil when the tool does not set them. The recognized keys are:

• :name - the tool's name, used by clients to call it. Required.
• :description - a human-readable description, or nil.
• :title - a short display title, or nil.
• :annotations - a tool_annotations/0 map of behaviour hints (:readOnlyHint, :destructiveHint, and so on), or nil.
• :_meta - a free-form metadata map passed through to the client, or nil.

use GenMCP.Suite.Tool generates this callback from the :name, :description, :title, :annotations, and :_meta options, with a catch-all clause returning nil. Implement it by hand only when the metadata is computed rather than static:

def info(:name, _arg), do: "search_files"
def info(:description, _arg), do: "Searches for files matching a glob."
def info(:annotations, _arg), do: %{readOnlyHint: true}
def info(_key, _arg), do: nil

@callback input_schema(arg()) :: schema()

Returns the schema describing the tool's accepted arguments.

The Suite normalizes this to JSON Schema and sends it as the tool's inputSchema in tools/list, so clients know what arguments to provide. The return may be a plain schema map or a defschema module:

def input_schema(_arg) do
  %{
    type: :object,
    properties: %{query: %{type: :string}},
    required: [:query]
  }
end

use GenMCP.Suite.Tool generates this callback from the :input_schema option, and from the same option also generates validate_request/2 that enforces the schema on each call.

@callback output_schema(arg()) :: nil | schema()

Returns the schema describing the tool's structured result, or nil.

Optional. When given, the Suite normalizes it to JSON Schema and advertises it as the tool's outputSchema in tools/list, so clients know the shape of the structuredContent to expect. It is purely descriptive and is not enforced against the result at runtime.

use GenMCP.Suite.Tool generates this callback from the :output_schema option. Like input_schema/1, the return may be a plain schema map or a defschema module:

def output_schema(_arg) do
  %{
    type: :object,
    properties: %{files: %{type: :array, items: %{type: :string}}}
  }
end

@callback validate_request(GenMCP.MCP.V2607.CallToolRequest.t(), arg()) ::
  {:ok, GenMCP.MCP.V2607.CallToolRequest.t()}
  | {:error, String.t() | Exception.t()}

Validates, and optionally transforms, the request before call/3 runs.

Returns {:ok, request} to proceed (with a possibly rewritten request), or {:error, reason} to reject the call with an invalid-parameters error, in which case call/3 is never invoked. The reason may be a message string, a JSV.ValidationError, or any exception.

use GenMCP.Suite.Tool generates this callback from the :input_schema option: it validates request.params.arguments against the schema and, on success, replaces them with the validated value (a struct when the schema is a defschema module). Defining validate_request/2 yourself stops it from generating one, which is how you validate by other means:

def validate_request(request, _arg) do
  case request.params.arguments do
    %{"limit" => n} when n in 1..100 -> {:ok, request}
    _ -> {:error, "limit must be between 1 and 100"}
  end
end