Guide · Concepts

Skills vs. tools vs. REST.

Three ways something can show up in Munin’s API. They overlap enough that people treat them as synonyms, then wonder why their agent retries a stripe refund five times in a row. They aren’t the same shape, and they aren’t the same audience.

REST the load-bearing layer

The HTTP API at /api/v1/*. Every business operation Munin can perform lives here first — channels, conversations, contacts, KB, agents. It’s how the dashboard talks to the backend, how integrations push data in, and how every other surface in this article gets its work done underneath.

Shape: Conventional REST: nouns as resources, verbs as methods, Zod-validated JSON bodies, RLS on every read. OpenAPI-described so you can generate clients.
Audience: Mostly admin. A small slice (the widget endpoints, end-user conversations) accepts self_service credentials.
When to use: Anything your own code calls. Backend integrations, scheduled jobs, the dashboard, scripts. If a human or a deterministic program is making the request, REST is the right surface.

MCP tools REST, shaped for an LLM

Tools are the same operations as REST, exposed through the Model Context Protocol. Each tool is a typed function the agent can call — a name, a JSON-schema input, a description the model reads to decide whether to invoke it.

Shape: One JSON-RPC endpoint at /mcp, served at mcp.getmunin.com. The tool list is filtered by the caller’s audience. Inputs are validated by the same Zod schemas as REST.
Audience: Whatever the bearer token resolves to. An admin key sees the back-office toolset (channel setup, key rotation, KB writes). A delegated token sees the self-service subset (read your own conversations, place your own order).
When to use: Anywhere an LLM is the caller. The Munin agent runtime, Claude Desktop, anything that speaks MCP. The descriptions matter: they’re the prompt the model reads to pick a tool, not internal documentation.

Skills prose the agent loads on demand

Skills are Markdown files. They’re not functions the agent calls; they’re procedures it reads. A skill explains how to do something with the tools that already exist — “onboarding a new chat channel,” “handling a refund request,” “triaging a low-confidence intent.”

Shape: A .md file with YAML frontmatter (title, description, audiences) and a body written like a runbook — short, imperative, ordered. Indexed at startup and loaded into the agent’s context only when its description matches the situation.
Audience: Tagged the same way tools are. An admin-only skill won’t surface in a self-service agent’s skill list, so it can’t accidentally follow a runbook that calls tools it doesn’t have access to.
When to use: When the “how” is non-obvious, multi-step, or worth standardizing. Skills are how you encode institutional knowledge: which channel to use for what, what order to touch endpoints in, when to escalate.

How they relate

REST is the load-bearing layer; tools are REST with a coat of LLM-readable paint; skills are documentation about how to use the tools well. A skill that lists three tool calls in order is a skill that turns into a deterministic workflow if you read it strictly — but the whole point of writing it as a skill is that the agent can deviate when reality does.

REST → tools: Most tools wrap a REST endpoint with the same auth and validation. A new business operation gets added to REST first; the tool is a thin shim with an LLM-friendly description.
Tools → skills: Skills reference tools by name. A “refund a customer” skill cites commerce_get_order, commerce_refund_payment, and conv_send_message — and explains when to use each.
Skills are not tools: The agent can’t “invoke” a skill. It loads the text and follows the procedure with judgment. If you find yourself reaching for skill-as-API, you actually want a tool that wraps the workflow.

Picking the right one

My backend code needs to do X: REST. You’re writing deterministic code — types, retries, your own error handling. Tools and skills add overhead you don’t need.
The agent needs to perform an operation: Tool. Add or extend the MCP tool that wraps the underlying REST call, with a description aimed at the model.
The agent keeps doing the right thing the wrong way: Skill. The tools are right; the procedure is unclear. Write the runbook.
The agent retries a deterministic workflow: Tool, not skill. If a sequence of steps must happen in order with the same inputs every time, encapsulate it as a single tool. Don’t make the model rediscover the sequence on every turn.