Define an MCP tool as a module.

defmodule MyApp.MCP.GetWeather do
  use Noizu.MCP.Server.Tool,
    description: "Get current weather for a location",
    annotations: [read_only_hint: true]

  input do
    field :location, :string, required: true, description: "City name or zip"
    field :units, :enum, values: [:celsius, :fahrenheit], default: :celsius
    field :days, :integer, min: 1, max: 14, default: 1
  end

  output do
    field :temperature, :number, required: true
    field :conditions, :string, required: true
  end

  @impl true
  # ⟦𓏃𓃁𓇄𓂮⟧ call :: auto-generated pointer for public function call
  def call(%{location: location, units: units, days: days}, ctx) do
    Noizu.MCP.Ctx.report_progress(ctx, 0.5)
    {:ok, %{temperature: 21.0, conditions: "clear"}}
  end
end

use options

• :name — wire name; defaults to the module basename underscored (MyApp.MCP.GetWeather → "get_weather")
• :description — tells the model when and why to use the tool. Accepts a plain string or a verbosity variant list (see Noizu.MCP.Description)
• :descriptions — named description variants ([tag: "text", ...]) referenced by :verbosity_map/:runners (spec §3)
• :verbosity_map — [{verbosity_spec, tag}, ...] selecting a named variant by verbosity level
• :runners — [{{provider, model_matcher}, rules}, ...] selecting a named variant by {runner, model} (spec §3); see Noizu.MCP.Description
• :title — human-readable display name
• :annotations — keyword list of behavior hints (:read_only_hint, :destructive_hint, :idempotent_hint, :open_world_hint, :title)
• :icons, :meta — passed through to the wire definition
• :hidden — when true, the tool is omitted from tools/list responses but remains callable. Useful for internal or privileged tools.
• :category — free-form grouping label. Rides on the wire in _meta.category (merged into :meta) and is filterable through the built-in Noizu.MCP.Server.Tools.Catalog tool.
• :evals — a list of inline eval specs for description tuning (spec §4); each is [name: ..., prompt: ..., rubric: ...]. See Noizu.MCP.Eval. Evals are compile-time metadata for the mix noizu.mcp.eval harness and never appear on the wire.

Need several small tools in one module? See Noizu.MCP.Server.Toolkit.

Schemas

input do ... end declares the input schema with the field DSL — see the Tools & Schemas guide for field types. Arguments are validated against the compiled JSON Schema before call/2 runs (failures become isError: true results the model can correct), then delivered atom-keyed with defaults applied and :enum values cast to atoms.

Prefer raw JSON Schema? Use the escape hatch — arguments are then validated but delivered string-keyed, uncast:

input_schema %{
  "type" => "object",
  "properties" => %{"query" => %{"type" => "string"}},
  "required" => ["query"]
}

input_schema/output_schema also accept the schema as raw JSON text (decoded at compile time — malformed JSON is a compile error):

input_schema """
{"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]}
"""

output do ... end (or output_schema %{...}) declares outputSchema; map return values are validated against it and sent as structuredContent.

Return values from call/2

• {:ok, String.t()} — single text content block
• {:ok, map()} — structured content (requires/uses output schema if declared)

• {:ok, Content.t() | [Content.t()]} — explicit content blocks

• {:ok, ToolResult.t()} — full control

• {:error, String.t() | Content.t() | [Content.t()]} — tool execution error (isError: true, visible to the model)

• {:error, Noizu.MCP.Error.t()} — protocol error