Behaviour for MCP tools using the action-dispatched pattern.

Each tool exposes multiple actions under a single tool name. The use Wymcp.Tool macro generates the inputSchema from actions/0 (via Wymcp.Tool.Schema), handles dispatch via run_action/3, checks required properties, refuses unknown keys at any depth of data, applies defaults, injects hints, and formats errors.

Usage

defmodule MyApp.Tools.Tasks do
  use Wymcp.Tool

  @impl true
  def name, do: "tasks"

  @impl true
  def description, do: "Task management"

  @impl true
  def actions do
    %{
      create: %{
        description: "Create a task",
        properties: %{"name" => %{"type" => "string"}},
        required: ["name"],
        defaults: %{}
      }
    }
  end

  @impl Wymcp.Tool
  def run_action(:create, %{"name" => name}, _ctx) do
    {:ok, %{message: "Created #{name}"}, %{id: 1}}
  end
end

Action schema format

Each action in the actions/0 map is keyed by the action name: an atom that must not contain a newline (validated at each of the moments in "When schemas are validated" below, like :description). Each action must have:

• :description — human-readable description of the action, emitted verbatim into the action summaries (the tools/list action enum, the help index) and into help's tool and action levels. Must not contain a newline — validated at each of those moments. See "Consumer-authored text" below.
• :properties — JSON Schema properties for the action's data parameter, a map keyed by property name. A key that is not a string is rejected at each of the moments in "When schemas are validated" below, never converted to one — here and in every schema below it: a nested property, an "items" schema, an "additionalProperties" schema, whatever it holds. There, too, a "properties" must be a map and an "additionalProperties" true, false or a schema; nothing else in a property schema is checked (Wymcp.Tool.Actions states why, under "The action-schema invariant").

Optional fields:

• :required — list of unconditionally required property names (defaults to []). Every listed property name must be present in data (AND-semantics).
• :required_one_of — list of groups, where each group is a list of property names. At least one group must be fully present (OR-of-AND semantics). Combines with :required — both checks run, both must pass. Enforced at dispatch; surfaced by the help tool.
• :defaults — map of default values merged into data before dispatch (defaults to %{}), keyed by property name: every key is a string naming a property declared in :properties, a default carries no key the unknown-key gate would refuse from a caller in the same place, and no key may also appear in :required — validated at each of those moments.
• :notes — long-form notes surfaced by the help tool.
• :related — list of related action name strings surfaced by the help tool.
• :examples — list of example payload maps surfaced by the help tool.

Defaults are applied after the dispatch gates run: a value supplied via :defaults does not count toward satisfying :required or :required_one_of, and it fills only a key the caller omitted — the merge goes by key presence, so a caller sending the key as null keeps the null. Both checks run against the caller's data as received.

When schemas are validated

Action schemas are validated at two moments: at the tool module's own compile, for a module built with use Wymcp.Tool; and when your mount module compiles, via Wymcp.Router.init/1. A malformed schema (e.g. a :required_one_of group referencing a property name not declared in :properties, or a key outside the field list above) raises ArgumentError immediately, surfacing the misconfiguration before any request is served. Validation also rejects dead config it can localize to a nameable pair of declarations — a :required_one_of group that is a strict superset of another, a :defaults key that is also :required — and does not compute global properties of a schema.

Both moments run the same check, validate_callback_shape!/1, whose first part is Wymcp.Tool.Actions.validate!/1, so a rule holds identically at each. The tool-module moment is the macro's alone: a behaviour-only tool — one that declares @behaviour Wymcp.Tool without the macro — never runs it, and its schemas are first read at wire-in. The other is the wire-in site, which catches a schema however it was declared.

Which moment reports a given tool first is not fixed, and the ordering is not worth relying on. The macro's hook is @after_verify, which the compiler runs only once the whole compilation set is compiled — so when a mount module in that same set lists the tool, Wymcp.Router.init/1 raises during the mount module's compile and the hook never runs; the error names the mount file. A tool no mount module names is caught by the hook instead. Either way the build fails before a request is served, which is the guarantee — the file named in the error is the part that varies.

A tool that reaches neither moment is not covered here at all: a behaviour-only tool that is never wired in is first checked where a reader obtains one of its schemas, which raises rather than serve an action schema whose mandatory keys are missing or malformed (the read-side corollary, Wymcp.Tool.Actions).

Both moments read more than the action schemas. The callback-shape check calls every zero-arity callback — name/0, description/0, title/0, annotations/0, output_schema/0 and input_schema/0 alongside actions/0 — and at the mount-module moment init/1 then builds each tool's tools/list definition from them. All of them must be callable with no runtime state — they run during the consuming application's build, before config/runtime.exs and before any supervision tree exists. A callback reaching for either fails that build only where the reach raises, surfacing as its own error at the file of whichever moment reports the tool first, as above; a defaulted read silently supplies the compile-environment value, which is then what is served until the next build. Wymcp.Router's __using__/1 documentation states the contract that follows: what was validated is what is sent.

Example: OR-of-AND required group

get_pull_request: %{
  description: "Get pull request details",
  properties: %{
    "url" => %{"type" => "string"},
    "project_key" => %{"type" => "string"},
    "repo_slug" => %{"type" => "string"},
    "pr_id" => %{"type" => "integer"}
  },
  required_one_of: [["url"], ["project_key", "repo_slug", "pr_id"]]
}

Consumer-authored text

Wymcp emits consumer-authored text without altering it. Every string a consuming application writes for the framework to pass on — a tool's description/0, an action schema's :description, :notes, :related and :examples, property "description" values, Wymcp.Hint descriptions, and Wymcp.Router's :instructions and :server_info — reaches the wire exactly as written. The framework may add separation and structure around the text: it prefixes each action description with its action name to form the action summaries (Wymcp.Tool.Schema.action_summaries/1), sorts actions by name, places the summaries in JSON arrays, and joins them with a separator. It never edits the characters. Names — tool, action, property — are identifiers rather than prose and sit outside this contract, except that an action name is half of every joined summary, so the newline constraint below covers it too.

One constraint follows from the separator: neither an action schema's :description nor an action name may contain a newline. The action enum's description in tools/list joins the action summaries with a newline, a summary is <action>: <description>, and an embedded newline in either half would make the boundary between summaries ambiguous — so wymcp refuses such a tool at each of the moments in "When schemas are validated" above, instead of reshaping the text. No other consumer-authored field is ever joined, so newlines stay legal everywhere else, including the tool-level description/0 and :notes.

This module is the contract's definition home, and the surface is wider than one module: Wymcp.Hint descriptions and Wymcp.Router's :instructions and :server_info are consumer-authored text too, and are governed by the contract stated here rather than by a restatement of their own.

Return values from run_action/3

• {:ok, response_data} — success, response sent as JSON
• {:ok, response_data, hint_context} — success with hints; the framework calls hints/2 with the action and hint_context, injecting the result
• {:error, reason} — error; the framework calls handle_error/1 and sends the result as an isError response
• {:error, reason, hint_context} — error with hints; the framework calls handle_error/1, hints/2, and action_context/2, then sends structured JSON with error, hints, and optional context keys

The generated run/2

use Wymcp.Tool also generates run/2 — the framework's entry point to the tool. It takes a Wymcp.Context.t() and the raw arguments map, hands both to Wymcp.Tool.dispatch/3, and never touches the HTTP layer. One clause, guarded on the arguments being a map: everything a caller can get wrong about that map — including sending no action at all — is a dispatch gate's structured answer, never a missing clause. It returns:

• {:ok, content} — success
• {:error, message} — an error the tool answered with; classified :tool in telemetry

• {:error, message, :dispatch | :tool} — an error carrying its own classification: :dispatch means a gate rejected the call before the action handler ran (the generated run/2 returns this for its own dispatch-gate rejections), :tool means the tool ran and answered with an error

The classification surfaces as the error_kind metadata key on [:wymcp, :tool, :stop] — see Wymcp.Telemetry. A hand-written run/2 may use the three-element error form to classify its own gate rejections; the two-element form always classifies :tool. This error tuple is not run_action/3's {:error, reason, hint_context} — there the third element is a hint-context map consumed inside dispatch, never a classification atom.

Wymcp.Methods.ToolsCall builds the JSON-RPC response from the returned tuple; a return outside this vocabulary is a fault, contained as the next paragraph says.

A fault out of run/2 is contained rather than propagated, and this boundary contains all three kinds — a raise, an exit and a throw, in the request process. Wymcp.Methods.ToolsCall catches each of them and answers with isError: true and a JSON diagnostic body, so a tool need not guard its own run/2 defensively. errorType is "tool_fault" whatever the kind — the value names the boundary, not what happened at it — tool names the tool, exception carries the exception struct's name for a raise and "exit" or "throw" for the other two, and message carries the fault bounded: an exception's message, or an exit's or throw's reason. The reader is a client's LLM, and an error body may not spend its budget echoing what the tool was handed. The same fault emits [:wymcp, :tool, :error] (Wymcp.Telemetry), where that rendering rides as error and the term it was made from rides whole as crash_reason.

A linked process's abnormal exit is a signal the boundary cannot see: it kills the request process rather than unwinding through it, so no catch reaches it. A tool that links to a process that may crash still takes the request down.

Dispatch errors and self-correction

Six dispatch gates reject a call before the action handler runs, in this order: a key outside the arguments vocabulary, an absent action, an unknown action name, a missing :required field, an unsatisfied :required_one_of group, and an unknown key anywhere in data. Each answers with isError: true content rather than a JSON-RPC error, and each carries a help pointer naming the call that would explain the surface it just refused. The three data-level gates additionally carry an input_schema digest of the action's properties, required fields and defaults, plus a required_one_of member when the action declares any groups. The three above them carry no digest: at arguments level the vocabulary — action and data — is the whole contract, and the two action gates answer with the list of valid action names instead.

The unknown-key gate reads data against the action's :properties at every depth. Every object schema whose key set is closed refuses a key outside its property names: data itself, every object schema under it that declares properties and writes additionalProperties as neither true nor a schema — absent or false, since a schema carrying any other value there never registers — and one that declares no properties but writes additionalProperties: false, which admits no key at all. additionalProperties: true opens an object; an additionalProperties schema admits extra keys and closes their values by that schema; any other object schema that declares no properties stays free-form. The gate reads keys, never values — a value whose shape does not match its schema reaches run_action/3 as it came — and which keywords it follows is Wymcp.Tool.KeySet's to state. One answer covers every unknown key, and its size stays bounded however many the caller sent: unknown_count is their number, unknown lists the first ten in sort order as data paths, and allowed maps the data path of each object holding one of those to that object's property names, with "<any string key>" among them where an additionalProperties schema admits any string key — data itself under "" — so the retry needs no help call. A bulk call is refused whole, whichever item carried the key. Help and the input_schema digest publish the same closure, as additionalProperties: false on each nested object it applies to, so the schema a caller reads states what this gate enforces.

The gates that quote the call back — unknown_arguments, unknown_action and unknown_params — quote it under the rule Wymcp.Bound states in "What a refusal quotes": each quoted value goes through Wymcp.Bound.echo/1, and unknown_arguments lists the first ten unknown keys in sort order with unknown_count their number, the shape unknown_params has.

The division of labour between these gates and argument validation is deliberate: argument validation owns structure, dispatch gates own vocabulary. A wrong type — action not a string, data not an object — is a malformed request, and Wymcp.Methods.ToolsCall answers it as -32602 from two hand-written checks of its own. A wrong name is a vocabulary mistake, and a generic schema-path rejection would name no key and suggest no next action; a gate answers it in the tool dialect instead. One consequence is visible to a caller who makes both mistakes at once: the type error is answered first, and the stray key goes unnamed until the retry.

The gates run as one chain and the first to fire answers, so a call with several mistakes surfaces them one per attempt. The point is that a confident LLM can attempt a call and learn from the error without a help round-trip: the rejection is the documentation for the call it just refused. Wymcp.Help gates its own vocabulary — tool and action — through the same check_arguments/4, and renders its unknown-target errors through the same pointer helpers, so the vocabulary surfaces cannot drift into two error dialects. Types are the one carve-out: help hand-writes its schema, so it owns the types of the keys it declares and answers a mistyped tool or action from its own gate rather than as the framework's -32602 — the framework's two type checks cover only its own action/data keys (Wymcp.Help states the rule at its gate).

One rejection in this family is not isError content. An unknown tool name never reaches a tool module at all: the answer is -32602 (Invalid params), naming the tool that was asked for in the envelope's message — -32601 is reserved for methods the server does not implement, which are answered with HTTP 404, so an unknown tool carrying the same code at 200 would be indistinguishable by code alone.

The action-schema invariant

Stated in Wymcp.Tool.Actions, beside the chain that enforces it: the rule that a key outside the vocabulary is rejected and a key inside it reaches a validator, its three clauses, and the read-side corollary that an action schema obtained for reading carries its mandatory keys. The vocabulary and the format catalogue are here, because a consumer writes against them; the rule about them is there, because that is where it is enforced.

The callback-surface invariant

Every callback a wymcp behaviour declares optional is one the framework probes before calling, so its absence is a value; every other declared callback is required and verified when the module is wired in. That rule is the callback-surface invariant, and it holds across every wymcp behaviour — Wymcp.Auth included, which satisfies it by declaring nothing optional.

Three clauses, each with its own enforcement:

• optional implies guarded — Wymcp.CallbackSurfaceInvariantTest's optional column sweeps the framework's entry points with a tool that defines no optional callback at all.
• required implies verified at wire-in — validate_callback_surface!/1 runs at Wymcp.Router.init/1, and the compiler warns any module that declares the behaviour and misses one.
• called implies declared — enforced by nothing automatic. Both the check and the invariant test derive from behaviour_info/1, so a call site whose callback was never declared is invisible to them. Closing that would need static analysis of lib/ for module.<fun>() call sites, out of proportion to the risk; the gap is recorded here rather than hidden.

The callback-shape invariant

Every zero-arity callback this behaviour declares is shape-checked at a use Wymcp.Tool module's own compile and at the registration moment: a return without the shape below is refused at whichever runs first, by a message naming the tool, the callback, the shape and the value returned. That rule is the callback-shape invariant.

A map here is never a struct. A struct passes is_map/1 and then fails further in, naming no callback, so the check refuses one — although the callbacks' types say map(), because no typespec expresses a map that is not a struct.

The rule is about shape: whether a value is a string, a map or nil at all. What a well-shaped value contains is another layer's — the action schemas' is Wymcp.Tool.Actions' — or no layer's: wymcp holds no content rule the spec does not.

validate_callback_shape!/1 is the check. Wymcp.CallbackShapeInvariantTest derives its cells from behaviour_info(:callbacks), one wrong return per cell, so a zero-arity callback declared later fails that test until the check covers it.

Optional callbacks

Three callbacks are optional, and for each the framework probes the module before calling, so an absent one is a value rather than a crash:

• action_context/2 — returns a map of runtime context for the given action, or nil. Receives (action_atom, ctx), where ctx is the same Wymcp.Context.t() passed to run_action/3. Called by the help tool at action level and during normal action dispatch. The map appears under a "context" key in the response. The callback is optional in the strict sense: a tool that does not export it gets no "context" key, silently. When defined it must return nil or a map — any other return raises, on the dispatch and help paths alike. Read per-request data from ctx.assigns rather than the process dictionary — action_context may be invoked from a process that did not run the auth plug.
• title/0 — returns a display title for the tool, or nil. A tool that does not export it gets no "title" key in its tools/list definition.
• annotations/0 — returns an MCP annotations map, or nil. A tool that does not export it gets no "annotations" key in its definition.

Required callbacks the macro defaults

use Wymcp.Tool supplies working defaults for three required callbacks via defoverridable, so a macro user implements only name/0, description/0, actions/0 and run_action/3. A module implementing the behaviour without the macro must define all three itself — nothing probes for them:

• hints/2 — returns a list of follow-up action suggestions. Default: []
• handle_error/1 — formats an error reason into a string. Default: "Operation failed: #{inspect(reason)}"
• output_schema/0 — returns a JSON Schema map describing the structure of the tool's response, or nil. When present, tools/list includes "outputSchema" in the definition and tools/call validates the response against it, returning "structuredContent" alongside "content". Default: nil

The remaining two required callbacks — input_schema/0 and run/2 — come from __before_compile__ and are not overridable, which is why a tool with no action dispatch cannot use the macro at all. Wymcp.Help is the framework's one such tool; see its moduledoc.

A tool's tools/list definition is not a callback at all. The framework assembles it from the callbacks above, through Wymcp.Tool.build_definition/1, so title/0, annotations/0 and output_schema/0 are the whole of what a tool contributes to it beyond its name, description and input schema.

flowchart TD
    subgraph Tool Behaviour
        T[Wymcp.Tool] --> D["dispatch/3"]
        D --> A["action dispatch"]
        A --> R["handle_result/4"]
    end
    subgraph External
        T --> S[Tool.Schema]
        S -->|"fetch_schemas!/1"| AC[Tool.Actions]
        D -->|"action_names/1, fetch_schema/2"| AC
        D -->|"check/2, close_properties/1"| KS[Tool.KeySet]
        T -->|"validate!/1"| AC
        AC -->|"action_schema_keys/0"| T
        AC -->|"schema_offences/1, default_offences/2"| KS
        D --> C[Context]
        R --> HN[Hint]
        A -->|"module.run_action/3"| CB(Consumer Tool)
        R -->|"module.hints/2"| CB
        R -->|"module.action_context/2"| CB
    end