Behaviour and compile-time convenience DSL for MCP tools.

The DSL emits ordinary module functions, and schemas remain unmodified Elixir maps representing JSON Schema documents.

Failure has two shapes, and they are not interchangeable

call/2 can fail in two ways, and they reach the client differently:

# The call succeeded; the tool is reporting a bad outcome.
# tools/call returns a result with isError: true.
{:ok, Snodo.Result.error("hex.pm returned 503")}

# The request itself was wrong or could not be attempted.
# The JSON-RPC request fails with an error object and no result.
{:error, Snodo.Error.invalid_params("version must be a semantic version")}

The first is for anything the tool understands: an upstream service failing, a lookup finding nothing, a domain precondition being rejected. A client sees a normal response it can show a model, and one failing tool does not look like a broken server.

The second escalates to the protocol. Reserve it for a request that should never have been dispatched.

Arguments that are missing from the schema's required list, or that the installed validator rejects, never reach call/2. The router answers with an isError result naming the problem, as the 2026-07-28 tools specification asks, so a model can correct its call.

For compatibility, {:error, reason} without an Snodo.Error is normalized into a tool error result. Prefer an explicit Snodo.Result.error/2 for domain outcomes and a typed Snodo.Error when the JSON-RPC request must fail.

Schemas are advertised, and required arguments are enforced

input_schema/1 is published verbatim in tools/list. The router enforces its required list before dispatch, so a handler may pattern match on those keys; a call missing one gets an isError result. Every other keyword is advertised but only enforced when the runtime installs a Snodo.Schema.Validator; the default is pass-through. See Snodo.Schema.Validator.Basic for the bundled common subset.

A property may carry "x-mcp-header": "Name" to be mirrored into an Mcp-Param-Name header over Streamable HTTP. The annotation is checked when the tool compiles: see the Components guide for the rules.

A tool may also declare :title, :icons, and :metadata in use Snodo.Tool or with title/1, icons/1, and metadata/1. Icons use the same shape as resource and prompt icons. :metadata becomes _meta in tools/list. Direct implementations may omit these callbacks; the defaults are nil, [], and %{}.

use Snodo.Tool also accepts wrap:, a list of Snodo.Component.Wrap modules or {module, options} tuples. The wrappers run inside call/2 after router checks.