Skip to main content
Meerkat’s tool system is trait-based. You implement AgentToolDispatcher, and the engine handles dispatch, parallel execution, and result injection. MCP servers are first-class — register them and their tools appear alongside your custom tools with no code changes.

Mental model

At the concept level, tools answer one question: how does the agent act on the world? The important conceptual layers are:
  • custom tools you own
  • built-in tools Meerkat can compose
  • MCP-provided external tools
  • runtime visibility/scoping rules
The Rust trait example below is an implementation detail of that model, not the model itself.

Custom tools

Implement the AgentToolDispatcher trait:
ToolCallView is a zero-allocation borrowed view ({ id: &str, name: &str, args: &RawValue }). When the model requests multiple tool calls, Meerkat dispatches them in parallel.

MCP servers

Register any MCP server and its tools automatically appear in the agent’s tool set:
Config is stored in .rkat/mcp.toml (project) or ~/.rkat/mcp.toml (user). Supports stdio, streamable HTTP, and SSE transports. OAuth-protected HTTP servers discover auth at connect time; use rkat mcp login <name> or rkat run --mcp-auth interactive when browser login is needed. See the MCP reference for full details.

MCP Apps in UI hosts

A host with an isolated MCP Apps renderer can opt in with AgentFactory::mcp_apps(true). Its MCP connections advertise io.modelcontextprotocol/ui and capture the original tool definition, arguments, full CallToolResult and available UI resource before model projection. Headless factories leave this capability disabled. App authors use standard _meta.ui.resourceUri, ui:// resources and text/html;profile=mcp-app. UI-only result _meta remains in native session persistence, outside model requests and public transcript projection. Resource reads do not require the resource to appear in resources/list. ToolAudience separates model and app visibility while retaining normal tool scope and policy checks. MCP tools default to both audiences; explicit _meta.ui.visibility narrows them. An app-only tool is unavailable to model selection and deferred catalog search/load. Visibility is not authorization: every app action still enters the current member’s native tool policy. UI hosts submit ToolApplicationControlRequest through SessionService with a trusted, revalidatable ingress and an exact session/tool-call locator. Governed hosts must implement fresh tool-application authorization through their native work-policy owner. The prior agent run’s authorization is never reused. Resource context providers implement prepare_resource separately from tool-call credential preparation. Native session-service App IO can run while the model turn continues. Each request uses an executor minted by the original Agent with its current tool scope and configured hooks and review. Results without session effects or hook notices return without loading or saving the accumulated transcript. Actual effects and notices wait for that exact actor to apply them; persistent services commit them before response delivery. This decision uses the collected outcome, not readOnlyHint; a post-hook error or a disconnected caller does not cancel required settlement. Custom SessionAgent implementations that do not provide this executor keep serialized execution. The runtime binds live operations to the originating physical MCP connection. Retained views can replay without re-executing the tool; retirement, replacement or process restart refuses new IO against the old binding. App code cannot pick another server by supplying a name. Developer panels belong to the embedding product’s Console integration. An MCP App can use its own renderer for a versioned generated UI document without another host authoring contract.

Built-in tools

Meerkat ships with tool categories resolved per agent. Factory category flags default off; product surfaces may apply their own explicit preset (for example, the CLI defaults to --tools safe). Shell tools support allow/deny list security policies. Runtime tool visibility can also be shaped with mob overlays and turn-boundary tool-scope updates. See the built-in tools reference for parameter details. Image generation and web search are independent category decisions. Enabling either one does not implicitly expose general builtins. Conversely, disabling general builtins does not prevent a runtime-backed build from explicitly enabling one of those capabilities. Explicit enables fail closed when the selected runtime cannot provision the requested capability. The current direct rkat run, REST, and JSON-RPC session builders leave image generation at inherit. In a normal composite dispatcher, that can expose generate_image when the session identity, image machine, executor, planner, and blob store are wired and tool visibility policy permits it. The minimal no-builtins/no-shell path instead needs an explicit image-generation Enable to avoid the factory’s early return. These direct surfaces do not expose that enable switch. --allow-tool generate_image only narrows an already composed surface; it cannot provision missing dependencies or enable the category. For nontrivial Meerkat-owned tool families, companion skills provide the agent instruction manual. Tool descriptions stay short and schema-oriented; skills such as workgraph-workflow, schedule-workflow, task-workflow, and shell-patterns explain the operating posture for the tool family.

Execution contracts

Tool visibility and tool execution are separate decisions. A visible tool has an execution contract that declares the modes it supports:
  • fast execution for ordinary request/response calls
  • streaming execution with progress and cancellation policy
  • detached execution backed by a durable job record
The runtime resolves a call to one supported mode, applies the narrowest deadline in the chain, and supervises progress or cancellation through the same tool gateway. Detached execution records its restart class explicitly. For example, a background shell command is non_resumable: its durable job truth survives a host restart, but a lost subprocess becomes worker_lost and is never silently replayed. Tool definitions also carry source provenance, and dispatchers classify calls as read-only, mutating, or unknown. Hooks and policy layers receive those typed facts rather than inferring authority from a tool name.

Tool scoping

Tool visibility can change during a session without restarting the agent. Changes are staged then atomically applied at the turn boundary — the LLM never sees a tool list change mid-stream. External filters. Callers can stage an allow-list or deny-list filter programmatically through ToolScopeHandle. This is distinct from MCP server lifecycle management. Per-turn overlays. Mob flow steps can restrict tools for a single turn via TurnToolOverlay (allow + deny). The overlay is ephemeral — it’s cleared after the turn completes. Live MCP mutation. MCP servers can be added or removed from a running session. Additions connect the server and register its tools; removals drain in-flight calls before finalizing. Both are staged and applied at the next turn boundary. Composition rule: Most-restrictive wins. Multiple allow-lists intersect, multiple deny-lists union, and deny always beats allow. The conversation records a typed tool_config system notice when the tool set changes, and a tool_config_changed event is emitted to the event stream.

Live MCP controls

MCP servers can be added, removed, or reloaded on a running session via JSON-RPC, REST, MCP-server tools, or SDK helpers:
All mutations are staged and applied at the next turn boundary. Set persisted: true to write the change to disk config so it survives restart. See the RPC reference for full parameter details. Since 0.9.4 the tool_config_changed event that reports the outcome carries settled, which says whether the change is a settled lifecycle fact rather than a pending or draining step; it never said whether anything was written to config. Events and notices stored by 0.9.3 and earlier carry persisted in its place, so a reader should accept either key. The persisted field of mcp/add, mcp/remove and mcp/reload keeps its name and meaning.

Surface availability

See the built-in tools reference for the mechanical details of factory flags and per-build overrides.

Scoped tool grants

A build can mark built-in tool families, individual tool names and MCP servers grant-gated. A gated name is mounted, a gated family as if it were enabled, and every tool a gated MCP server provides is gated from the moment it appears, but each stays hidden from the model and is refused at dispatch until a live scoped tool grant that covers it is admitted. A grant never widens a session past its build: it opens only what the build gated, and the static tool policy, the application tool policy, governed authority, review and confinement all still apply to every call it opens.
  • Gating a build. In Rust, set grant_gated_tools on SessionBuildOptions or AgentBuildConfig, for example GrantGatedTools::default().with_family("shell").with_tool("deploy"); over JSON-RPC, pass grant_gated_tools ({"families": [...], "tools": [...]}) to session/create. The session records its gate, and a resume that names none restores it. The factory refuses a gate that no grant could honour with BuildAgentError::GrantGate: an unknown family, a gated family the build disables, a gated family none of whose tools the build mounts (comms tools mount only with a comms runtime), a gated name the build does not mount (a name a still connecting MCP server may provide is gated from the moment it appears), a name the build’s tool policy refuses, and a build without the runtime’s grant service. A gate that covers web_search, by name or through its family, disables the provider’s native tools for the session, including native search that the session’s or a turn’s provider params ask for, so the gated tool is the only search path.
  • Gating a mob member. A mob profile declares tools.grant_gated (grant_gated = { families = ["shell"], tools = ["deploy"] } in TOML; on mob/create, a realm profile or a mob/spawn profile override). At every member build, resume included, the member’s gate is its own profile’s gate joined with its role’s current gate. A store-owned identity declared with its role’s named profile is built from the role’s definition, as a worker of the role is: its own gate is the role’s current gate, less the families its declaration switches off. One declared with an exact profile of its own (profile_override) joins the role’s gate as role entries, as a member spawned with its own profile does. A family of the member’s own gate is mounted, closed by the gate, whatever its switch: leave the switch off, so a binary that does not know the gate keeps the family off. A role entry never fails the member’s build: a role tool name is gated from the moment it appears, a role family is gated where the member mounts it, and a role family the member does not mount (its switch off, or a spawn disabled it) or a role name the build’s tool policy refuses is ignored. A live member keeps the gate its build installed until its next build. A member whose own gate or role gate names anything cannot be placed on another host.
  • Gating MCP servers. A gate’s mcp_servers names MCP servers (in Rust, GrantGatedTools::with_mcp_server; {"mcp_servers": [...]} over JSON-RPC and in a mob profile’s grant_gated). A gated server need not be configured: it may be attached later, and its tools are gated by their provenance from the moment they appear; each model-request boundary also gates the names a gated server provides then, so a name such a server had stays gated for the rest of the build, whichever source provides it later. unconfigured_mcp_servers: true (with_unconfigured_mcp_servers) gates every MCP server the build does not configure itself, whatever path attaches it later (mcp/add included); the servers the build configures stay open. A host’s callback tools and tool bundles are never a server’s. A gated server the build configures starts no process until a live grant of that server covers it when a build reads the grants (a respawn or a resume): until then nothing of it is connected, and a call naming one of its tools finds no tool. The build decides this itself as it composes the session’s tools; MeerkatMachine’s gated stage (SurfaceStageGatedAdd, McpRouter::stage_add_gated) is the check of a grant-time live attach of a gated server, and its caller lands with the live attach. A tool name only a gated server provides is granted through its server, not by name. A role server, like a role tool name, is gated from the moment it appears and never fails the member’s build.
  • Granting. MeerkatMachine::grant_tool issues a grant for a subject (a session, or a mob member identity in one mob incarnation, ToolGrantSubject::member), a target (one tool name, a built-in family with the names it provides, which meerkat::tool_family_names answers, or an MCP server, optionally narrowed to some of its tools) and a window of at most the host policy’s maximum lifetime, 24 hours by default. A grant can also be scoped to one run of its subject (ToolGrantRequest::run_scope; over JSON-RPC, scope: {"kind": "current_run"} takes the run the subject is running now, an identity’s being the run of the session its member holds, and is refused with run_not_active when it runs none): it then admits uses of that run only, and ends with it; a member’s end of its run ends the run-scoped grants of its identity and of its session. revoke_tool_grant, list_tool_grants and read_tool_grant_audit complete the Rust API; ToolGrantService offers the same operations over any RuntimeStore. Grant a mob member identity with MobHandle::grant_member_tool: the mob’s actor decides it against its live roster as it commits, in order with the retirements that end an identity’s grants, so a member retired before the commit is refused and a retirement after the commit ends the grant. The direct writers, MeerkatMachine::grant_tool and ToolGrantService::grant with a member subject, do not consult the roster: a grant they write for an identity that has retired is issued, and a name seated again in the same incarnation holds it. Over JSON-RPC, tool_grants/grant, tool_grants/revoke, tool_grants/list and tool_grants/audit serve them for sessions and mob member identities (see scoped tool grants over JSON-RPC), and the Python and TypeScript SDKs wrap them; tool_grants/grant commits an identity grant through the mob’s actor. A member’s build reads its identity’s grants first, then its session’s, so an identity grant follows the member across respawns and restarts; its grants end when its identity ends, and a reset of its mob, which ends every identity the mob held, ends them too.
  • Requesting. A host can ask for a grant that a person approves instead of issuing it: MeerkatMachine::request_tool_grant, or tool_grants/request over JSON-RPC (Python request_tool_grant, TypeScript requestToolGrant), holds a durable decision of kind tool_grant.issue (see durable decisions) and issues nothing. Every gated build also mounts the tool request_tool_grant, itself ungated, through which the agent asks for one of its gated names or families: it names the target, duration_ms and a reason, never the session or the approver, and the call returns at once with the pending request (a replayed call answers the request it held; a call for a target the session’s subject already has an open or approved window request for joins that request while it is open, and holds a new one after it ends; a joined request keeps its own duration, which can differ from the one asked, and the answer says the call joined and gives that duration_ms). The session’s host holds it with what it takes requests with (MeerkatMachine::set_tool_grant_request_host: the decision owner, the approver policy and the requester its agents are named by; rkat-rpc takes them while it runs the executor), or the call answers that the host takes none. Once a person approved the decision, the executor of the kind (ToolGrantIssueExecutor, which rkat-rpc runs) issues the grant under an id derived from the decision, with the decision as its issuer and its window starting then; a review stage’s allow never issues one. A list shows an open request as requested and, with ended grants, a recently rejected, expired, withdrawn or refused one as declined; the session receives an input when its request ends (a member identity’s request reaches the session its member holds then, through the mob’s member input).
  • Adjudication. Every model-request boundary first gates the names each gated MCP server provides now, then opens the gated names a live grant admits at that moment, in the boundary’s run (a server grant opens its server’s gated names then), and every gated call is adjudicated again immediately before it is handed to its tool, so a call at or after the deadline is refused even when the boundary that showed the tool ran before it. A run-scoped grant admits only the calls of its own run: a call outside any run is refused and leaves the grant live for its run, and a call or boundary of a later run ends it. A build belongs to no run, so a run-scoped server grant starts no gated server the build configures; it opens the names of a gated server that is attached during its run. The dispatch gate authorizes a gated MCP call before the host prepares it (McpCallContextProvider::prepare), so a refused call never selects a credential. A refusal is an ordinary policy_denied tool error with the code tool_grant_required, tool_grant_expired, tool_grant_revoked or tool_grant_unavailable (a grant that ended with its run, or a run-scoped grant asked outside its run, opens nothing: tool_grant_required), which the model reads as Tool call denied (<code>): <message>; a call of a closed gated tool behind the deferred catalog is refused the same way. When the grants cannot be read, or a boundary cannot gate a gated server’s names, the gate stays closed and the session records a warning notice.
  • Lifecycle. The canonical ToolGrantLifecycleMachine owns each grant: issued, then expired at its fixed deadline, revoked before it, or, for a run-scoped grant, ended with its run before it. The run’s end ends the grant when the run completes, fails or is cancelled (a run a hard interrupt dropped included), when durable-tail recovery closes a run a stopped process left open, and otherwise at the first use of a later run of the session. Recovery ends the session’s run-scoped grants of the run it closes; a member identity’s run-scoped grants of a recovered member run end at the member’s next run’s first use, or at their deadline. Ended grants stay ended across restarts and host clock rollbacks. The runtime’s deadline timer expires a served session’s grants on time, and a list or audit read settles the due grants of any session without loading it; nothing about a grant wakes a dormant member. Grants live in the runtime store, on SQLite in the runtime-tool-grants schema domain that the first write of a grant or audit row creates (a refused call’s audit row is one). With the in-memory store, Web/WASM included, they last only for the process.
  • Audit. Each subject’s grants append to one audit log: granted (with the grant’s scope), expired (with the driver that observed the expiry), revoked, run_ended (with the run and the driver that ended it: run at the run’s end, recovery, or the boundary or dispatch of a later run) and refused rows. A lifecycle row commits with the grant’s change; a failed refusal row never admits the call.
  • Limits. The dispatch gate is the authority; what the model is shown follows it at the next model-request boundary. A live session keeps the tool surface its live bridge opened with, so a name a grant opened stays visible there after the grant ends, and the dispatch gate refuses each call. A control-plane tool, such as the deferred catalog’s search and load tools, is never hidden by a gate; a gated one is refused at dispatch until a grant opens it. A grant row this binary cannot read (written by a newer binary, or damaged) opens nothing and blocks none of its subject’s other grants; a list reports it, and an audit read reports an audit row it cannot read and serves the rest of the page. A binary older than run scopes reads a run-scoped grant’s row, and its granted and run_ended audit rows, so: it never takes a run-scoped grant for a window grant. A binary older than grant requests reads the grant an approved request issued as unreadable, so it opens nothing there. A binary older than scoped tool grants does not know a session’s gate: it resumes a gated session with its gated tools ungated, so upgrade every host that serves gated sessions before relying on a gate.
A scoped tool grant confers no authority of its own: it only opens, for a bounded time, names the build gated. Governed authority grants (Agent authorization) decide whether an operation may run at all, and an application tool policy’s member tool grants (CompiledMemberToolGrant) decide which tools a member may use and with what consequence. Both still apply to a call a scoped grant opened.

Asking a person (ask_user)

From 0.9.15. ask_user lets an agent put a set of multiple-choice questions to a person and continue once they are answered. It is a stock tool that a host mounts: meerkat-core defines the tool, its typed questions, answers and outcomes and the seam a host implements (AskUserHost), and no build has the tool until its host mounts it. A Rust host mounts it by putting an AskUserDispatcher over its AskUserHost into the build’s host tools (SessionBuildOptions::host_tools), which the agent factory composes beside the build’s own tools and which leave the build’s tool catalog as it is. Meerkat Meta mounts it for mob members and answers it in its Console (see “Question sets” on that page). No Core surface mounts it: not rkat, rkat-rpc, the REST server, the MCP server or the Web SDK.
  • Arguments. questions (required), an optional title and an optional timeout_seconds. Each question has an id, a prompt and choices (each an id and a label), and may set allow_free_text (the person may write their own answer instead of a choice; off when absent) and recommended (the id of the choice the agent recommends; it is shown to the person and never preselected). Put the questions that belong together in one call: a person answers one set at a time.
  • Limits. 1 to 10 questions, each with 2 to 8 choices. An id is 1 to 32 bytes of a-z, 0-9, _ and -, unique among the set’s questions or the question’s choices. A prompt is at most 1024 bytes, a label 256, the title 200. recommended names a choice of its own question. timeout_seconds is 60 to 604800 (7 days) and defaults to 3600. A free-text answer is 1 to 280 bytes. A call outside these limits is refused as invalid arguments and asks nothing.
  • The result comes in two steps. The call returns at once; it never waits for the person. Its result is {"outcome": "asked", "request_id", "answer_by", "answers": [], "note"}: the questions are now with a person, request_id names the request and answer_by is its deadline. The answers arrive later as an input of their own, labelled ask_user_result: {"outcome", "request_id", "answers": [{"question_id", "answer"}], "note"}, where each answer is {"kind": "choice", "choice_id"}, {"kind": "free_text", "text"} or {"kind": "unanswered"}. The input starts a turn of an idle agent, and the same request_id ties it to the call.
  • Outcomes. At the call: asked, or no_human_surface when the host has nowhere to show the questions to a person (nothing is held, and no later input follows). In the later input: answered (the person sent answers; a question they left out reads unanswered), dismissed (the person declined to answer), timed_out (nobody answered before answer_by; every question reads unanswered) and withdrawn (the host ended the request before a person decided it).
  • Free text is data. A free-text answer is the person’s own words about the question asked. An agent reads it as an answer, not as instructions that change what it may do: the person’s authority over the agent is whatever the host gave them, and an answer adds none.
The questions and their end are held by the host. In Meta a set is a durable decision of kind ask_user.questions: it survives a restart, ends at its deadline, and the result reaches the asking agent once.

Multimodal tool results

Tools can return rich content beyond plain text. The injected runtime shape is ToolResult.content: Vec<ContentBlock>, with helper constructors for text-only or multimodal output.
  • ToolResult::new(...) — the standard text-only path. The string becomes a single text content block.
  • ToolResult::with_blocks(...) — returns one or more content blocks directly, including images and video.
  • Built-in tools that expose richer output may internally use ToolOutput::Blocks(...), but the persisted/runtime-facing result shape is still ToolResult.content.
ContentBlock is non-exhaustive and currently has five variants:
  • ContentBlock::Text { text } — plain text content.
  • ContentBlock::Image { media_type, ... } — inline or blob-backed image content.
  • ContentBlock::Video { media_type, duration_ms, ... } — inline or URI-referenced video content. Video blocks are accepted only on Gemini user-message input paths and are rejected in tool results. Vertex Gemini can consume gs:// references directly; Gemini API sessions can consume public or already-registered file URIs, and register gs:// references first when the session has Google bearer auth.
  • ContentBlock::Structured { data } — canonical opaque JSON returned by a tool without first stringifying it into text.
  • ContentBlock::SkillContext { skill_key, text } — runtime-authored skill activation context with its canonical source identity preserved.
The built-in view_image tool reads an image file from disk and returns a result containing image content blocks. It supports PNG, JPEG, GIF, WebP, and SVG formats up to 5 MB. The tool is automatically hidden from models that lack vision support via capability-aware tool visibility. The built-in generate_image tool is session-owned runtime dispatch. It lets a model request generated or edited images through universal fields plus provider-owned provider_params. Generated image bytes are stored as blobs and committed as AssistantBlock::Image transcript blocks, so every surface reads the same image_id/blob_ref history and fetches bytes through blob/get or model-facing blob_save_file. The blob file bridge tools are registered only when the session has a blob store. blob_save_file writes decoded blob bytes to a file inside the project root, blob_load_file reads a project file into the blob store, and blob_inspect returns blob metadata without raw payload bytes. They do not expose blob listing or deletion. apply_patch and blob_save_file run in the host process and never write the engine’s own directory (a .rkat directory at or below the project root) or a path the host declares as its own state or input; see paths the file tools never write. Custom tools can return text, image, or structured content through ToolResult::with_blocks(...). Video tool results are rejected, and SkillContext is reserved for the runtime skill-injection path.

Image generation

generate_image is a session-owned tool for creating or editing assistant images. It is registered when the runtime-backed surface supplies the image-generation machine, provider executor, planner, and blob store. In the normal composite dispatcher, Inherit is visible once that substrate is wired. The category can also be enabled independently from general builtins through a Mob profile or an in-process override_image_generation: Enable. The tool accepts a typed request under request, routes it to OpenAI or Gemini image backends, stores generated image bytes in the realm blob store, and returns structured ImageGenerationToolResult JSON with durable images[].blob_ref values. A model can then call blob_save_file to materialize that blob as a project file, for example top-news-infographic.png. For setup, provider parameters, result fields, and troubleshooting, see Image generation.

Composition

Tools from different sources (custom, MCP, built-in) are composed into a single dispatcher. The agent sees one flat tool list regardless of where each tool comes from. Hooks can observe tool calls before and after execution, and guardrails can deny unsafe calls before dispatch.

Mob tools (meerkat-mob-mcp)

Mob tools (mob_*) are provided by the meerkat-mob-mcp dispatcher and composed through the late-bound SessionBuildOptions.mob_tools factory slot.
  • CLI run composes this dispatcher when the full tool preset is selected (--tools full or --yolo).
  • rkat mob ... remains the explicit direct lifecycle surface.
  • Other session-driven surfaces can grant the same agent-side mob_* capability by installing AgentMobToolSurfaceFactory into their session build path.
  • Public host APIs should not re-export that raw dispatcher. They use typed control planes instead: mob/* on RPC/SDK surfaces and meerkat_mob_* on public MCP surfaces.