Skip to main content

Overview

This inventory combines the meerkat-tools builtin dispatcher with the runtime-composed memory, comms, schedule, WorkGraph, mob, image-generation, and web-search surfaces. Each family remains the source of truth for its own tool names, schemas, execution contract, mutation class, and gates. In the table, Default means enabled inside an already-selected tool family. It does not mean a bare AgentFactory exposes that family. Product surfaces may apply explicit presets of their own.

Enabling and disabling tools

AgentFactory controls which tool categories are available via builder methods:AgentFactory is the only place tool categories are composed. The public meerkat::AgentBuilder delegates to the factory path with explicit client/tool/store overrides. The lower-level meerkat_core::AgentBuilder is not re-exported by the facade and is not a public standalone embedding API. See AgentBuilder vs AgentFactory.Source: crates/meerkat/src/factory.rs — AgentFactory struct and builder methods.
Each AgentBuildConfig can override factory-level flags for a single agent build:All default to inherit. The categories backed by factory flags inherit those flags. Image generation treats inherit as visible once its session-owned substrate is wired into the normal composite dispatcher. The minimal no-builtins/no-shell early return requires an explicit image enable to create that dispatcher. The Meerkat-owned web-search fallback is different: it treats inherit as hidden and requires an explicit enable. An explicit enable fails closed if its runtime dependencies cannot be provisioned. Enabling either category does not enable general builtins.Source: crates/meerkat/src/factory.rs — AgentBuildConfig struct.
Individual tools can be enabled or disabled via ToolPolicyLayer in BuiltinToolConfig, but policy can only select tools from a category that was actually composed. When shell is enabled, the factory applies a policy that activates the four standard shell tools (which have default_enabled: false). The high-trust monitor_start and all five skill tools also default off and require an explicit policy enable in a custom dispatcher build.
Every dispatcher exposes a ToolExecutionContract per tool. The default is Fast; tools may additionally support Streaming or Detached. Streaming contracts own progress/cancellation policy. Detached contracts declare runner identity, submission idempotency, restart class, and a bounded submission deadline. The resolved deadline is the narrowest contribution in the call’s deadline chain.RestartClass values are Adoptable, CheckpointResumable, Replayable, and NonResumable. A tool can advertise only the classes its runner can honor.Separately, every dispatcher reports ToolMutationClass::ReadOnly, Mutating, or Unknown. Unknown is fail-closed uncertainty for third-party or undeclared tools, not an assertion that the call is harmless.
Capabilities are registered via the inventory crate in crates/meerkat-tools/src/lib.rs:
  • Builtins (CapabilityId::Builtins): task_list, task_create, task_get, task_update, datetime, apply_patch, view_image, and runtime-backed blob_save_file/blob_load_file/blob_inspect when a blob store is available. Controlled by config.tools.builtins_enabled.
  • Shell (CapabilityId::Shell): shell, shell_jobs, shell_job_status, shell_job_cancel, plus opt-in monitor_start. Controlled by config.tools.shell_enabled and per-tool policy.
  • Image generation: runtime-owned generate_image, controlled by override_image_generation after runtime capability resolution.
  • Web search: provider-native search when the active model owns it, otherwise the Meerkat-owned web_search fallback; controlled by override_web_search.
  • Schedule (CapabilityId::Schedule): meerkat_schedule_*. Controlled by config.tools.schedule_enabled.
  • WorkGraph (CapabilityId::WorkGraph): workgraph_*. Controlled by config.tools.workgraph_enabled.

Runtime tool scoping

Beyond static factory flags and per-build overrides, tool visibility can be changed at runtime during a live session. See Tool scoping for the conceptual overview.
ToolScope (in meerkat-core) manages runtime tool visibility. It holds the base tool set from the dispatcher, an active external filter, and an optional per-turn overlay.Staging: External callers stage filter updates via ToolScopeHandle::stage_external_filter(filter). The staged filter is NOT applied immediately — the current turn is unaffected.Boundary apply: At the start of each CallingLlm loop iteration, tool_scope.apply_staged(dispatcher_tools) atomically promotes the staged filter to active, prunes stale tool names, and returns the visible tool set. A ToolConfigChanged event is emitted and a typed tool_config system notice is recorded in the conversation.Filter types:
  • ToolFilter::All — no restriction (default)
  • ToolFilter::Allow(set) — only listed tools are visible
  • ToolFilter::Deny(set) — listed tools are hidden
Composition: Most-restrictive wins. Multiple allow-lists intersect, multiple deny-lists union, deny beats allow.Persistence: The active external filter is stored in session metadata under tool_scope_external_filter and restored on session resume.Source: crates/meerkat-core/src/tool_scope.rs
MCP servers can be added or removed from a running session. Operations are staged on the McpRouter and applied at the next turn boundary.Servers being removed transition through Active → Removing (draining) → Removed to allow in-flight tool calls to complete before finalization.Source: crates/meerkat-mcp/src/router.rs, crates/meerkat-rpc/src/handlers/mcp.rs
Mob flow steps can restrict tools for a single turn via TurnToolOverlay:
The native allow/deny fields are Option<Vec<ToolName>>; .into() converts the names above. The default supplies an empty host-only dispatch_context. Set the overlay on StartTurnRequest.runtime.turn_tool_overlay by the flow engine or another trusted per-turn producer. It is ephemeral — cleared after the turn completes — and composes with the external filter using most-restrictive semantics.Public wire requests use the caller-safe PublicTurnToolOverlay shape: allowed_tools and blocked_tools contain string names. They do not accept the internal dispatch_context field.Source: crates/meerkat-core/src/service/mod.rs, crates/meerkat-mob/src/runtime/flow.rs

Deferred tool catalog control plane

An exact dispatcher can keep eligible session tools out of the LLM’s inline schema set and expose two always-inline control tools instead. The adaptive selector enters deferred mode when a source is still pending, at least two eligible tools exist, or their combined name, description, and schema volume reaches 160 bytes. These tools are not part of the general builtins gate. A Rust host can read this projection for a live session without a model request: EphemeralSessionService::tool_catalog_view and PersistentSessionService::tool_catalog_view (and the MobSessionService seam) return a typed ToolCatalogView. It reports the mode the next request takes, sources still connecting, whether a staged change waits for the next boundary, and for each catalog entry its deferral eligibility, callability and visibility (Visible, Deferred behind the control plane, or Hidden). Reading it changes nothing. Like the other tool-scope snapshot queries, it is not exposed over JSON-RPC or REST.
Search deferred-eligible session tools without loading them.
String
Optional case-insensitive substring search over canonical name and description.
usize
default:"10"
Result limit, clamped to 1-50.
The response contains catalog_exact, total_matches, results, optional pending_sources, and optional empty_result_status. Each result reports name, description, currently_callable, and visibility_status: loaded, deferred, blocked_by_filter, or temporarily_unavailable. pending_source is used only as the empty-result status while a catalog source is pending.Source: crates/meerkat-tools/src/control_plane.rs
Stage one or more canonical deferred tool names for the next tool boundary. The control plane consults the bound ToolScope and fails closed when it has no authoritative visibility state.
String[]
required
One or more canonical tool names.
The response contains catalog_exact, accepted_names, noop_names, and one resolution per requested name. Rejection reasons are unknown_key, not_deferred_eligible, not_filterable, or temporarily_unavailable. Already staged or visible names are successful no-ops. Accepted loads take effect at the next boundary, not during the current tool call.Source: crates/meerkat-tools/src/control_plane.rs, crates/meerkat-core/src/tool_catalog.rs

Model-switch tool

brain_swap is available only when the host can realize committed model handoffs, more than one distinct model is reachable, and tool policy permits it. Its required target_model argument selects from that reachable set. The tool returns staged or already_staged; it does not change the model during the current run. A clean run completion commits the request, which the runtime attempts to realize before processing the next input. Failed, interrupted, or hook-denied runs do not commit the switch, and later realization can still be denied or held. A staging result is not proof that the model has changed. The switch keeps the session’s reasoning effort level and is not judged against it. After a brain_swap to a model whose route does not accept the session’s level, each request is refused before it reaches the provider until the level is changed or cleared. Source: crates/meerkat-tools/src/builtin/brain_swap.rs, crates/meerkat-tools/src/builtin/composite.rs, crates/meerkat-core/src/agent/state.rs, crates/meerkat-runtime/src/service_ext.rs

Mob tools

AgentMobToolSurface is composed only for sessions with generated MobMachine authority. It defines the 13 core tools in the inventory above, including fork_off for durable transcript-forked work and council for bounded discussion among temporary forks of existing members. Realm profile storage adds five profile CRUD tools; a parent-owned snapshot provider also adds mob_profile_list_sources. Admission is then checked again at each dispatch against the current typed mob, spawn, profile-mutation, or objective scope. See Mob tools for argument shapes and workflows. mob_list lists a mob only when its actor admits that the caller may manage it. A persisted mob whose store did not restore is quarantined and has no actor, so mob_list never lists it: the check fails closed. Hosts list quarantined mobs through mob/list and the MCP meerkat_mob_list tool (see Quarantined mobs and degraded members).

fork_off and council delivery

fork_off forks the calling member’s committed transcript into a durable child member, commits the task (and any expected_output guidance) as the child’s input, and admits the child’s one turn. The child runs turn-driven whatever its role’s default runtime mode, like a delegate helper. What happens next depends on whether the host can deliver a completion after the call returns. The child, like a local council participant, is built with its source member’s build inputs: the source’s application context and labels and the source’s per-spawn tool overlay. The labels that name a member (mob_id, role, profile_name, meerkat_id, agent_identity) are not inherited. The child’s roster entry carries none of them, and its build stamps the child’s own. Its SessionBuildOptions::fork_source names the source member and the session the child was forked from, so a host build callback can grant the child exactly the source’s tools and instructions. With the same tools, the child’s first request repeats the source’s cached prompt prefix. The host’s spawn customizer does not run on the child’s seating. A child that is rebuilt later (revived after its session was dropped, resumed, or restored after a restart) keeps its fork_source, labels and application context. The host’s spawn customizer does not run on those rebuilds either, so it cannot change them. It is revived with the tool overlay it was built with. After a restart or explicit resume it gets the overlay its source is restored with, as long as the source is still seated on the session the child was forked from. Once the source has been retired or respawned, the child is rebuilt with the overlay the host’s spawn customizer gives its own identity, and a warning names the missing source. A fork of the child inherits the overlay the child was built with, so grandchildren get the same tools. A grandchild follows its source only while every ancestor its tools came through is still seated on the session its fork was taken from, so it drops a retired ancestor’s tools too. Its tools came through only the ancestors they passed when it was forked: if its forker had already been rebuilt with its own identity’s tools by then, the grandchild keeps following its forker, whatever happened above it. Detached. A call runs detached when three things hold: the host declares it can deliver later, it has a runtime to admit the completion, and the caller can be made live again to receive it. A host built with a runtime adapter declares delivery by default (the JSON-RPC, REST, and MCP servers and Meta), and so do rkat run --keep-alive and rkat mob deploy --surface rpc. The caller can be revived when it is a member of a mob the host manages (its mob revives it) or when the host installs a DetachedOwnerHost (the JSON-RPC host does). A fork_off caller is always a mob member. There fork_off returns without waiting for the child’s turn:
Neither this result nor the blocking one carries the fork’s cache_inheritance. That is prompt-cache accounting for hosts (it stays on the Rust ForkMemberResult and the SDK fork results); request building never reads it, and a mob fork always reports it unavailable, which says nothing about what the child’s turn is billed. The child’s cache cost is the usage in its completed outcome. When the child’s turn ends, its outcome names the child (agent_identity, member_ref) and carries a status: The outcome is recorded once, durably, in the forker’s own transcript as a BackgroundJob system notice. Its body is the header “Background fork_off job <job_id> finished (<status>):”, where the status is completed, terminated for a max_run_secs autokill, or failed for every other outcome. Its typed block, SystemNoticeBlock::BackgroundJob, carries the job_id, the tool name, that status, the outcome JSON as detail (stored only there), and persisted: true, which marks it as a durable completion record rather than a progress notice that is refreshed at each model call (SystemNoticeMessage::persisted_background_job_id finds it). The model sees the header followed by the outcome, once. It stays in the transcript across later model calls, turns, and reloads, and it remains readable after the child is retired: in the transcript the model sees, and through the forker’s session history (session/history over JSON-RPC, GET /sessions/{id}/history over REST). The record is delivered to the forker’s session as a runtime input with steer handling and the idempotency key fork_off:<job_id>, so it is written exactly once however often delivery runs:
  • a forker in the middle of a turn sees it in that same turn: the notice is written into the running turn at its next model call (after that point’s tool results), every later model call of the turn sees it, and it commits with the turn, with no second turn. Only when the turn ends before another model call (the model answered without a further tool call) does the forker get exactly one follow-up turn that sees it;
  • an idle forker runs exactly one wake turn that sees the outcome, and the notice is committed with that turn;
  • a forker that is no longer live (the runtime retired its idle executor, or the host restarted) is revived through its mob first.
Blocking. A one-shot host may exit when the turn ends and so cannot deliver a later completion. The rkat CLI is one-shot unless it stays alive: rkat run without --keep-alive and the other one-shot rkat mob commands. There fork_off waits for the child and returns the completed result as its tool result (bounded_result, usage, turns, tool_calls, and the child’s identity and sessions). A child that does not complete is a tool error whose text carries the same outcome. A blocking result names why it blocked in blocked_because: host_declared_unavailable; no_runtime_adapter for a host that declares detached delivery but has no runtime (which also logs an error); or no_owner_revival_host for a caller that is a plain session on a host without a DetachedOwnerHost. A blocking call leaves no detached job owed, so no result can be lost. Neither form has a default deadline: the child runs for as long as its task needs. The agent loop’s default tool deadline does not cut a blocking call. An operator’s explicit tools.tool_timeouts.fork_off entry still bounds it, as does a deadline the host itself imposes on tool calls. max_run_secs is an opt-in autokill, honored in both forms, that cancels the child’s run and retires the child once it has run that long; omit it for no limit. fork_off rejects arguments it does not define, so a misspelled or invented field is an argument error instead of a silently ignored intent. Across a restart. A detached child carries a durable job record (job id, forker session, start time, opt-in limit, fork prefix length, result bound, and, on a runtime-backed host, the stable delivery identity its job turn is admitted under) on its spawn event and roster entry. When a host restores its mobs, or inserts a restored mob handle as Meta does, a one-time re-link pass settles every child whose job began in a previous process:
  • a child whose reply to the job is already in its durable transcript has that reply delivered, however late the restart landed, and stays seated. For a job with a delivery identity (every job on a runtime-backed host) the outcome comes from the runtime’s terminal receipt for the job turn’s input instead, so a child whose transcript was compacted during the job is still delivered its real reply, with the turn’s usage, turns and tool_calls. That receipt also settles the other outcomes: the turn’s own failure is failed with its error, and the child is retired as the live custodian retires it; an end imposed from outside (the runtime stopped or destroyed, the turn cancelled), an input no run answered, or one never admitted is restart_interrupted. So is an input that a settlement of the child’s session answered as outcome unknown (a run consumed it at a boundary a recovery committed without its receipt): that receipt carries no reply, so none is delivered. An input still owed a terminal is watched until it has one, even while the child reads idle (a requeued input waiting for the recovered run). A record without a delivery identity (written by an earlier release, or on a host without a runtime) reads the reply from the child’s transcript after the fork prefix;
  • a child still running is observed until its turn ends, with max_run_secs measured from the original start. A turn that is terminal in the child’s live agent counts as running until its boundary commit lands: the re-link asks the child’s runtime whether a run input still awaits its boundary (MeerkatMachine::session_has_uncommitted_run_input), so a finished reply is read only once it is durable;
  • otherwise restart_interrupted is delivered and the child stays seated.
Waiting on a commit is bounded. The re-link keeps watching a child whose member status reads settled while its commit is unconfirmed for at most COMMIT_PENDING_CEILING (5 minutes), measured from the first such reading and restarted only when the child is seen running again. The commit is unconfirmed while the runtime shows machine evidence that it has not landed (a run input still staged or applied, or degraded durability after a failed boundary commit), or while the runtime’s read is inconclusive (it timed out behind a busy session driver, or failed). At the ceiling, unless a durable reply has appeared, restart_interrupted is delivered. It carries restart_reason: commit_never_landed only when the reading at the ceiling was machine evidence; an inconclusive reading names no cause. For a job with a delivery identity the same ceiling bounds an input still owed its terminal while the child is not seen running; there commit_never_landed means a run had taken the input up (staged or applied) and it never reached a terminal. At that ceiling the receipt is read once more, waiting on the runtime for up to two seconds (never past max_run_secs), and a receipt found then is delivered. Only a read that is evidence (the input still owed a terminal, never admitted, or the child without a session or retired) delivers restart_interrupted; a read that says nothing (it timed out behind a busy session driver, such as the turn’s own commit, even after an earlier reading found the input pending, or it failed) keeps the watch going, and only three such reads in a row deliver restart_interrupted, naming no cause. A limit that has already elapsed is decided at once, so an idle child past its limit always gets max_run_elapsed. When the limit wins, the child’s run is cancelled, max_run_elapsed is delivered, and the child and its descendants are retired once that delivery settles (submitted durably, or the owner gone). A submission that fails keeps the cancelled child and its job record, and a later pass delivers and retires it; a child left seated after its record was committed is retired by the next pass without a second record. A retirement the settled outcome requires (the turn’s own failure, or max_run_elapsed) that fails is retried for up to about ten seconds, within that child’s own settlement, so it never holds up another child. One that still fails is reported, as ChildRetirement::Failed in the pass’s ForkRelinkReport (and in the ForkRelinkOutcome of fork_relink::relink_child) and as a logged warning, and the child stays seated until the next pass retires it. The job’s owner is its bound owner session, never read back from the child’s roster entry: a member of the child’s mob or of another mob the host manages is revived through its mob, and any other owner is a plain session made live through the host’s DetachedOwnerHost. A fork_off child’s owner is its forker, a member of the same mob; a forker that was respawned or retired since is gone, so the job is reported as owner gone and a child past its limit is retired with its descendants. Delivery is the live custodian’s: the outcome is committed once with the job (a ForkJobTerminal event in the child’s mob, with the outcome’s result digest) and submitted to the owner as a continuation under the same record and idempotency key (fork_off:<job_id>), so an outcome recorded before the restart is never recorded twice, and an idle forker is woken to see it. A job whose outcome is already committed is submitted with that outcome. A job whose completion was already admitted is finished: the pass leaves it and its child alone (no limit, no cancel, no second record), and a respawned child carries no job, although its ownership still follows the identity. A job whose forker no longer exists is reported as owner gone instead of retried. The continuation is durable from submission: a forker that cannot be served yet, because its mob is not running (for example restored Stopped after a clean shutdown) or is still being revived, receives it from the host’s delivery owner once it is, with no wait or retry of the pass’s own. MobMcpState::relink_restored_fork_children runs the pass explicitly. council follows the same split. Detached, it returns status: "running", the council_id, a job_id, and a note, and the sealed outcome (result, cleanup, replayed) is recorded and delivered the same way, as a “Background council job <job_id> finished” notice with the idempotency key council:<job_id>. A council that fails after the call returned is recorded with {"error": ...} as its outcome and status failed, and so is a sealed council whose exit reason is a failure (participant_seating_failed, participant_fork_instruction_refused, participant_source_replaced, wiring_incomplete, exchange_failed, coordinator_interrupted), whose record keeps the full sealed outcome. A detached council also survives a restart: its custody record carries the convener’s job, and the post-restore recovery sweep delivers the council’s sealed result, or coordinator_interrupted once the dead coordinator’s claim lease has expired (councils are never re-executed). The sweep runs on every host whose council store is durable and whose MobMcpState was built with into_shared() (a state wrapped in a plain Arc::new never runs it), and it retries after the earliest observed lease expiry; MobMcpState::relink_detached_councils runs the re-link explicitly. Blocking, council returns the sealed outcome as its tool result, with blocked_because. A council’s outcome is committed once on its custody record and submitted as a continuation like a fork_off outcome. A detached convener that is not live is revived when its continuation is applied: through its mob when it is a mob member, or through the host’s DetachedOwnerHost when it is a plain session. A plain-session convener on a host without that hook (a top-level REST, MCP-server, or rkat run --keep-alive session) is not given the detached route at all: its council runs in the call and returns with blocked_because: "no_owner_revival_host". MobMcpState::detached_delivery_blocked_because_for(owner) reports the route for a given caller. Its own timeout_seconds bounds it in both forms, and the agent loop’s default tool deadline does not. See Temporary Councils. An embedding host declares the capability on its MobMcpState (with_detached_completion_delivery / set_detached_completion_delivery with DetachedCompletionDelivery::Available or Unavailable). The default follows the presence of a runtime adapter, and detached_delivery_blocked_because reports why the tools would block. Detached outcomes are submitted through the host’s runtime delivery inbox, which the host binds with MobMcpState::bind_continuations (passing the bundle’s runtime_delivery_inbox() and continuation_bindings()); a host that does not bind it runs the tools in the turn (no_continuation_owner). Every product surface binds it. A host whose detached-job owners can be plain sessions installs a DetachedOwnerHost (with_detached_owner_host / set_detached_owner_host) so their results are applied after the runtime retired an idle executor. Bind continuations and install the hook before inserting restored mob handles: mob_insert_handle starts the re-link. compose_rpc_mob_state does this for the JSON-RPC host.

Forked children belong to their forker

Ownership follows the process tree. A child created by fork_off belongs to the member that forked it, and so does every member that child forks in turn; ownership never flows upward. The spawner is recorded durably when the child is seated, survives resume and respawn (including a respawn with a successor spec), and is checked against the caller’s own session binding, never against tool arguments. Without manage scope over the mob, the forker can still:
  • read any of its descendants with mob_check_member, which answers at once even while the member’s turn runs (progress.run_state is run_open, the output preview and token count are from its last completed turn, and a note says so). Status reads of different members never hold each other up, and concurrent reads of one member share one read; a session read that outlives its 1 s deadline keeps running (and keeps its share of the mob’s read capacity) until it finishes, for at most 30 s, and later reads of that member wait on it instead of starting another. A read still running after 30 s is given up and its share released, so a stalled session store cannot hold the mob’s read capacity for longer. A read whose session view was not observed still answers, with a typed preview_unavailable meaning the preview and token count are missing, not empty or zero, and a note chosen by its value: observation_deadline (the read did not finish in time) and read_failed say to check again later and that only status and progress.run_state are current; session_absent says the member has no readable session, so checking again will not bring the preview back; store_refused says the store refuses to read the member’s session until its realm is reopened, so checking again will not bring the preview back before then, and that status and progress.run_state are current; not_observed_while_retiring says the member is retiring and its session was not read;
  • retire any of its descendants with mob_retire_member;
  • list its descendants, and only those, with mob_list_members.
A profile’s member operator tools (member_status, retire_member, force_cancel_member, list_members) apply the same rule. With manage scope, all of these tools reach every member, as before. A host can hide members from other members’ operator tools (MobBuilder::with_member_tool_audience): member_status, retire_member and force_cancel_member answer a member its audience hides from the calling member exactly as a member the mob does not hold, with manage scope too, and do nothing to it. From 0.9.15 these tools keep to the audience as well: mob_check_member and mob_retire_member answer a member the audience hides in the same way; wire_members, unwire_members, mob_wire and mob_unwire answer so for either member they name, and council for a participant; spawn_member and spawn_many_members answer so for the source of a fork launch, and refuse a resume of a session bound to such a member as a resume of a session nobody holds; list_members and mob_list_members leave such a member out of the list and out of every listed member’s wired_to; and the report of mob_destroy, and the refusal of a mob_destroy refused by the mob, name no such member. An agent is answered such a refusal whole only when its type shows that it names nothing the agent is not shown; any other is answered as mob destroy refused. The destroy can be retried; the host's log has the cause., on a host with no audience too, and the host’s log holds it whole at warn. A placed member’s calls are asked about as that member’s. The audience is handed the labels the calling member and the target carry on their own roster rows, so its rule can rest on a member’s durable labels. From 0.9.15: the other mob tools of an agent (mob_spawn_member, fork_off, council, conclude_objective, mob_check_member, mob_retire_member, mob_list_members, mob_wire and mob_unwire) follow the same rule for a mob that has an audience: a refusal the mob answers is passed on whole only when its type shows that it names nothing but the mob and the members the call itself names, and any other is answered as the mob refused the call. The host's log has the cause., the whole refusal logged at warn. When the refusal has a class that describes the refused operation (wiring_error, session_error, storage_error and the like) the answer ends with Refusal class: <class>. and carries it as class in its data. A provider authentication failure keeps its typed data, and a retirement still in progress keeps retryable: true. The outcome of a fork_off run and the error of a council that could not run follow the same rule; a council that started and then failed answers its outcome with the mob’s own texts. A mob with no audience answers these tools whole, with one exception on every host: a failed read of the calling session’s own seat (fork_off, conclude_objective) is answered as a fixed text unless its type names nothing. Through 0.9.14 every mob answers these tools whole. A call that seats a member still tells whether its name is taken. In 0.9.11 through 0.9.14 only the three tools named first keep to the audience. A member list names a member the audience hides. Through the wire tools a member with manage scope over the mob can learn that a member hidden from it exists and reach it. Through mob_check_member and mob_retire_member, on a host that has not wrapped the two tools, a member can learn that a member hidden from it exists, and one with manage scope over the mob can read its status and retire it. The fork and resume launches and council are not held to the audience. The report of mob_destroy can name such a member, and a destroy the mob refuses because a member’s state could not be restored names that member, its session and the cause to every caller. A placed member’s operator calls reach the audience as a call no member made. The CHANGELOG lists each of these under Security and Fixed. A member placed on a member host holds manage scope over its mob, including the privileged spawn arguments, unless its controlling host narrowed it with an operator authority ceiling on its spawn request. See Placed-member operator authority. Retirement cascades like a process tree. Retiring a member retires every member it transitively spawned, deepest first, then the member itself, each through the same exact-incarnation retire; every retirement is attempted and the first failure is reported, so a retry converges. The cascade lives in the core retire, so every path takes it: mob_retire_member, retire_member, the max_run_secs autokill, the retirement of a child whose turn failed, host-side retirement (mob/retire over JSON-RPC, meerkat_mob_retire over MCP), and MobHandle::retire itself, which Meta’s retire paths and idle sweep use. A descendant forked while its subtree is being retired is retired with it. The mobs the retired member created itself and its delegates end with its session, at the next start of the host. A child whose own turn fails is retired automatically. A child whose turn completes stays seated, for inspection or further work, until its forker retires it. Meerkat adds no retention limit of its own; a host can apply one (Meta’s idle_retire_secs, for example). Host/operator surfaces for placement, binding, grants, observation, live member sessions, and hard cancellation are control-plane APIs, not agent builtins, so they are intentionally excluded from this inventory. Source: crates/meerkat-mob-mcp/src/agent_tools.rs

Schedule tools

Schedule tools are the agent-facing scheduler surface. They are distinct from the host APIs (schedule/* over RPC and /schedules/* over REST).
These tools are provided by ScheduleToolDispatcher in meerkat-schedule and are gated by the scheduler capability.

WorkGraph tools

WorkGraph tools are the agent-facing write path for durable work. Host RPC, REST, and CLI expose observability; CLI and trusted hosts add narrow goal and attention controls.
For operating guidance, load the workgraph-workflow companion skill when it is available. For the data model and host observability surfaces, see WorkGraph reference.

Task tools

Task tools provide structured work tracking. They are enabled by default when builtins are on. With the session-store feature, factory-built sessions use a session-scoped SqliteTaskStore, so resume restores the same task set. Builds without that feature use FileTaskStore when a project root exists and MemoryTaskStore otherwise.
A Task object returned by task tools has these fields:Source: crates/meerkat-tools/src/builtin/types.rs — Task struct.
Create a new task in the project task list.Default enabled: Yes
String
required
Short subject/title of the task.
String
required
Detailed description of what needs to be done.
String
default:"medium"
"low", "medium", or "high".
String[]
default:"[]"
Labels/tags for categorization.
String[]
default:"[]"
Task IDs that this task blocks.
String[]
default:"[]"
Task IDs that block this task.
String
default:"null"
Owner/assignee.
Object
default:"{}"
Arbitrary key-value metadata.
Returns: The created Task object (see task data model above).Source: crates/meerkat-tools/src/builtin/tasks/task_create.rs
Get a task by its ID.Default enabled: Yes
String
required
The task ID to retrieve.
Returns: The Task object matching the given ID.Error: ExecutionFailed if the task ID is not found.Source: crates/meerkat-tools/src/builtin/tasks/task_get.rs
List tasks in the project, optionally filtered by status or labels.Default enabled: Yes
String
default:"null (all)"
Filter by status: "pending", "in_progress", or "completed".
String[]
default:"null (all)"
Filter by labels (tasks matching any label).
Returns: Array of Task objects matching the filters.Source: crates/meerkat-tools/src/builtin/tasks/task_list.rs
Update an existing task. Only provided fields are modified; omitted fields remain unchanged.Default enabled: Yes
String
required
The task ID to update.
String
default:"unchanged"
New subject/title.
String
default:"unchanged"
New description.
String
default:"unchanged"
New status: "pending", "in_progress", or "completed".
String
default:"unchanged"
New priority: "low", "medium", or "high".
String[]
default:"unchanged"
Replace all labels.
String
default:"unchanged"
New owner/assignee.
Object
default:"unchanged"
Merge metadata (set key to null to remove).
String[]
default:"[]"
Task IDs to add to the blocks list.
String[]
default:"[]"
Task IDs to remove from the blocks list.
String[]
default:"[]"
Task IDs to add to the blocked_by list.
String[]
default:"[]"
Task IDs to remove from the blocked_by list.
Returns: The updated Task object.Error: ExecutionFailed if the task ID is not found.Source: crates/meerkat-tools/src/builtin/tasks/task_update.rs

Shell tools

Shell tools execute commands and manage background jobs. They are all default_enabled: false. The effective shell category must first be composed; the factory then uses ToolPolicyLayer to activate the four standard shell tools. A policy cannot create an absent shell category, and monitor_start still requires its own explicit policy enable.
background: true is available only when the session has a persistent realm job store and blob store. Submission, status, result references, cancellation, and terminal delivery are durable. The shell worker itself is non_resumable: if its process is lost across restart, the committed attempt becomes worker_lost after its existing lease expires and is never silently replayed.
command: "some-command &" and background: true are different contracts. An ampersand is only syntax interpreted by the selected shell. Meerkat still executes that shell invocation through the foreground tool path, returns the ordinary foreground result, and does not create a job ID or a record visible to shell_jobs, shell_job_status, or shell_job_cancel. Any child the shell leaves running is unmanaged and its lifetime is not guaranteed. Use background: true when the command must be managed as a Meerkat shell job. It commits and returns a stable job ID and enables durable status/list/cancel operations. This does not claim that the subprocess survives a host restart: the durable record survives and reports the non-resumable worker loss.

Timeout hierarchy

Tool execution has layered deadlines; the narrowest applicable layer wins. Changing the normal Meerkat tool timeout cannot extend a narrower shell, SDK/builder ToolDispatcher, or Meta callback deadline. The foreground shell and dispatcher deadlines are distinct enforced layers, even though both defaults come from ToolTimeoutPolicy; a config’s [shell] timeout_secs sets the shell’s. Background shell submission returns within the normal tool call, but the spawned command keeps its own shell timeout. The command runs under one fenced non-resumable attempt; terminal state is committed before runtime notification delivery.
Shell behavior is controlled by ShellConfig:Source: crates/meerkat-tools/src/builtin/shell/config.rs
The SecurityEngine validates commands before execution using POSIX-compliant word splitting (shlex) and glob pattern matching (globset).The engine parses the command into an executable and arguments, canonicalizes that complete invocation, and matches the full canonical string against the pattern set.Source: crates/meerkat-tools/src/builtin/shell/security.rs
Execute a shell command. Uses POSIX-style parsing for policy checks; runs via Nushell or fallback shell.Default enabled: No (requires shell to be enabled)
String
required
The command to execute (POSIX-style parsing for policy checks).
String
default:"Project root"
Working directory (relative to project root).
u64
default:"Config default (30)"
Timeout in seconds, at least 1.
bool
default:"false"
If true, durably submit a non-resumable shell job and return its stable job ID. Requires persistent realm job and blob stores, and is advertised to the model only when they are bound. Job truth survives restart; a lost subprocess is classified as worker_lost, not replayed.
A foreground result reaches the model as compact text: one status line, then stdout as is, then stderr under a [stderr] line only when it is non-empty. Flags such as invalid UTF-8 appear only when set. Transcripts, tool events and every surface carry this text as a Text content block. Only code that calls the tool directly (BuiltinTool::call) gets the typed ShellOutput through ToolOutput::into_json.stdout is capped at [shell] max_output_chars characters (default 40000, about 10K tokens), and stderr at half of that. The cap applies to foreground calls and background jobs alike. Longer output keeps up to half the cap from its start and the rest from its end. A cut moves to a line boundary when the line it lands in fits the cap. The marker between the two sides names the omitted lines, the line where the head ends and the line where the tail starts, and a sed -n range that pages exactly the omitted lines:
When a line is longer than the cap, the cut falls inside it and the marker says which lines were cut and suggests narrowing the command instead.
Invalid UTF-8 is decoded lossily. The typed ShellOutput records it in stdout_lossy and stderr_lossy, and the text result notes it. A character split by the capture buffer’s edge is not invalid output and is not flagged.
Source: crates/meerkat-tools/src/builtin/shell/tool.rs
Start an explicitly enabled, high-trust durable script monitor. Unlike an ordinary background shell command, the monitor consumes a typed output protocol and can publish notifications, checkpoints, progress, and completion. Notifications do not complete the job.Default enabled: No. enable_shell alone does not grant this high-trust tool; an embedding surface must enable it through tool policy. Persistent realm job and blob stores are required.
Restart class is a declaration enforced by the detached execution contract, not a promise inferred from the command text. Replayable and resumable scripts must implement the corresponding idempotency/checkpoint behavior.Source: crates/meerkat-tools/src/builtin/shell/monitor_tool.rs
List all background shell jobs.Default enabled: No (requires shell to be enabled)Parameters: None (empty object).
The summary status field is one of: "queued", "running", "completed", "failed", "cancelled", "worker_lost", or "needs_attention".Source: crates/meerkat-tools/src/builtin/shell/jobs_list_tool.rs
Check status of a background shell job. The model sees compact text: the job ID and its state, and for a completed job its exit status and output, capped like foreground output. Transcripts and events carry the same text; only code that calls the tool directly gets the typed BackgroundJob through ToolOutput::into_json. A background job’s completion notice carries the same exit status and output.Default enabled: No (requires shell to be enabled)
String
required
The job ID to check.
Error: ExecutionFailed if the job ID is not found.Source: crates/meerkat-tools/src/builtin/shell/job_status_tool.rs
Request cancellation of a running background shell job. For a live process, success returns cancellation_requested; this is not a terminal acknowledgement. Poll shell_job_status until it reports cancelled. Meerkat publishes terminal cancelled status only after the worker proves the complete process group has been contained. Synthetic jobs with no live process may return cancelled immediately because there is nothing to contain.Default enabled: No (requires shell to be enabled)
String
required
The job ID to cancel.
Error: ExecutionFailed if the job ID is not found.Source: crates/meerkat-tools/src/builtin/shell/job_cancel_tool.rs
JobId format: "job_" followed by a UUID v7 string.JobStatus variants: Queued, Running, Completed, Failed, Cancelled, WorkerLost, and NeedsAttention (serialized as lowercase snake_case status tags). A command timeout is represented by the worker’s terminal failure facts; there is no current TimedOut enum variant.Source: crates/meerkat-tools/src/builtin/shell/types.rs

Memory tool

The memory search tool lives in the meerkat-memory crate and is composed into the tool dispatcher as a separate MemorySearchDispatcher (implementing AgentToolDispatcher). It is NOT part of CompositeDispatcher — it is wired via ToolGateway when the memory-store-session feature is enabled and enable_memory is true.
Search semantic memory for past conversation content. Memory contains text from earlier turns in the current session that were compacted away to save context space.
String
required
Natural language search query describing what you want to recall.
usize
default:"5"
Maximum number of results to return (max: 20).
The limit is capped at 20 regardless of the requested value.
source_range is the half-open [start, end) offset range of the source message(s) the entry was indexed from. Memory is scoped to a single session; results do not carry a session_id, and there is no cross-session recall.Returns an empty array if no matches are found.Source: crates/meerkat-memory/src/tool.rs

Utility tools

Utility tools are general-purpose helpers enabled by default when builtins are on.

Paths the file tools never write

apply_patch and blob_save_file run inside the host process, so no OS process confinement applies to them. They refuse to create, change, delete or move:
  • any path in a .rkat directory, the engine’s own, at the project root or in any directory under it: the project’s MCP servers (mcp.toml), hooks (config.toml) and skills, and, with the CLI’s default project-local state, the realm’s config document and stores. A host started from a subdirectory reads that directory’s .rkat, so a nested one is refused like the one at the root. The name is matched in any letter case, through .., an absolute path or a symbolic link, and when the directory does not exist yet.
  • any path the host declares as its own state or input that lies inside the project root, with everything under it: the realm state root (also one given with --state-root), the realm’s documents (config.toml, config_state.json, realm_manifest.json, the authorization directory), the user config document, the MCP, hook and skill sources and a file credential store. rkat, rkat-rpc, rkat-rest and rkat-mcp declare theirs. A Rust host declares its own with AgentFactory::with_protected_host_inputs (or CompositeDispatcher::protect_host_paths on a dispatcher it builds itself); without it only .rkat/ is refused.
  • any path with a symbolic link whose target does not exist: the write would create the link’s target, wherever it points.
The refusal is an ordinary invalid-arguments tool error, returned to the model, and nothing is written. Reading (view_image, blob_load_file, an update hunk’s context of an ordinary file) is not restricted by this rule, and neither is the shell tool, whose reach its confinement decides. To change engine configuration, use the CLI (rkat mcp add, rkat config, rkat auth, rkat skill add) or edit the files yourself. A declared path that contains the project root, or is the project root, is not applied as a whole. That is the layout of rkat-rpc and rkat-mcp started without --context-root: they root these tools in the realm directory itself. The realm’s documents are refused there like everywhere else, with the hooks and skills read from that directory’s .rkat, and other files are written as before. The realm’s stores (sessions, runtime, jobs, tasks, blobs and the rest) lie in the same directory and are not refused in that layout. Start the server with --context-root <dir> (SDK option context_root / contextRoot) to give agents a project directory of their own and keep the whole realm out of these tools’ reach. rkat-rest without a context root roots the tools in its own instance directory, which does not hold the realm. Three limits of the rule: a hard link that already exists in the project to a protected file is written through; a symbolic link deeper inside a protected directory is not followed (the rule follows a link at <project root>/.rkat and at each declared path, so the directory such a link leads to is refused under its own name; a link inside it to another place is not); and a .rkat below the project root that is itself a symbolic link is refused by its name, not where it leads.
Get the current date and time. Returns ISO 8601 formatted datetime and Unix timestamp.Default enabled: YesParameters: None (empty object).
Source: crates/meerkat-tools/src/builtin/utility/datetime.rs
Apply a line-oriented patch that can add, update, move with edits, or delete files inside the project root. This tool is classified Mutating.
String
required
Patch text wrapped by *** Begin Patch and *** End Patch. File operations use *** Add File:, *** Update File:, optional *** Move to:, and *** Delete File: markers. Update hunks use literal @@ context plus space, -, and + line prefixes.
Paths must be project-root-relative. Lexical and symlink escapes are rejected. A pure rename is not supported: a move must include at least one update hunk. Multi-file patches are applied in order and are not transactional, so an error after an earlier operation can leave that earlier operation applied.Every path of the patch (each add, update and delete target and both ends of a move) is checked before the first change against the paths the file tools never write. A patch that names one is refused with an invalid-arguments error and applies none of its operations.The JSON result reports status: "success" plus added_files, modified_files, and deleted_files.Source: crates/meerkat-tools/src/builtin/utility/apply_patch.rs
Read an image file from the project directory and return its contents as a base64-encoded ContentBlock::Image. This enables vision-capable models to analyze images from disk during tool use.Default enabled: Yes (when builtins are on and the model supports image tool results)
String
required
Path to the image file, relative to the project root.
Supported formats: PNG, JPEG, GIF, WebP, SVG.Size limit: 5 MB. Files exceeding this limit return an error.Capability gating: view_image is currently hidden via ToolScope when the active model does not support image content in tool results (ModelProfile.image_tool_results == false).Returns: A content-block result containing a single ContentBlock::Image with the base64-encoded image data and detected media type.Source: crates/meerkat-tools/src/builtin/utility/view_image.rs
Save decoded bytes from the session blob store to a file inside the project root. This is the model-facing equivalent of materializing a blob with rkat blob get, but it remains sandboxed to the active project.Default enabled: Yes when builtins are on and the runtime-backed session has a blob store.
String
required
Blob ID to save.
String
required
Destination path, relative to the project root or absolute within the project root. A path in .rkat/ or in another of the paths the file tools never write is refused before anything is created.
Boolean
default:"false"
Whether to replace an existing file.
Returns: JSON metadata: blob_id, media_type, path, and bytes_written. Raw bytes are never returned in the tool result.Source: crates/meerkat-tools/src/builtin/utility/blob_file.rs
Read a file inside the project root and store its bytes in the realm blob store.Default enabled: Yes when builtins are on and the runtime-backed session has a blob store.
String
required
Source path, relative to the project root or absolute within the project root.
String
default:"inferred from extension"
Optional media type. When omitted, Meerkat infers common image, text, JSON, CSV, SVG, and PDF media types from the file extension.
Size limit: 25 MB.Returns: JSON metadata: blob_id, media_type, path, and bytes_read. Raw bytes are never returned in the tool result.Source: crates/meerkat-tools/src/builtin/utility/blob_file.rs
Inspect a blob without returning its raw payload.Default enabled: Yes when builtins are on and the runtime-backed session has a blob store.
String
required
Blob ID to inspect.
Returns: JSON metadata: blob_id, media_type, and decoded size_bytes.Source: crates/meerkat-tools/src/builtin/utility/blob_file.rs
Generate or edit an assistant-owned image through the session image-generation substrate. Generated bytes are committed to the realm blob store and returned as durable AssistantImageRef values.Tool policy default: Yes after the category has been composed. Factory category default: Inherit, which is visible in the normal composite when the image-generation machine, executor, planner, session identity, and blob store are wired. A minimal no-builtins/no-shell composition needs explicit Enable; Mob profiles and in-process builds can use that override without opening general builtins. See the guide for the current surface matrix.
Object
required
Image generation request. The simple shape supports intent, prompt, instruction, source_images, reference_images, size, quality, format, count/n, target, provider, model, and provider_params.
Common request:
Targets: auto uses the current provider’s image profile when available. Use provider: "openai" or provider: "gemini" to force a provider default. Use provider plus model to force a provider-owned image model.Supported universal options: size accepts auto, 1024x1024, 1024x1536, 1536x1024, or WIDTHxHEIGHT; quality accepts auto, low, medium, high; format accepts auto, png, jpeg, jpg, webp; count is currently limited to 1.Provider params: Use top-level size, quality, format, and intent for normal requests; these are Meerkat fields, not raw provider params. For the current gpt-image-2.6-sunburst default, OpenAI provider_params should normally be limited to background, output_compression, moderation, hosted-tool-only action, hosted-tool-only reasoning_effort, and hosted-tool-only web_search; background is auto, opaque or transparent (transparent needs format png or webp; with jpeg it is denied with projection_unsupported), output_compression applies when format is jpeg/webp, moderation is auto or low, action is usually omitted in favor of top-level intent, a low, medium or high reasoning_effort also sets a GPT Image 2.6 model’s planning complexity, and input_fidelity is not accepted by Meerkat. Gemini accepts aspect_ratio and image_size.Returns: ImageGenerationToolResult JSON containing operation_id, terminal, images, provider_text, revised_prompt, native_metadata, and warnings. Each generated image includes blob_ref.blob_id, which can be saved from inside the session with blob_save_file or fetched externally with rkat blob get <blob_id> --output image.png.Source: crates/meerkat-tools/src/builtin/image_generation.rsSee Image generation for provider behavior, examples, and troubleshooting.

Web search fallback tool

The active model may receive provider-native web search directly in its provider request. When the active model lacks native search and web search is explicitly enabled, AgentFactory can instead compose the Meerkat-owned web_search fallback against a configured OpenAI, Gemini, or Anthropic search executor. The explicit enable fails closed if no executor can be provisioned.
String
required
Non-empty natural-language search or research query.
String
Optional assertion: openai, gemini, or anthropic. When present it must match the fallback provider selected for the session.
String
Optional brief conversation context used to disambiguate the query.
The result is WebSearchResult: status, query, optional provider and model, optional answer, typed evidence, provider-observed native_events, optional error, and checked_at. Native events are evidence from the provider, not Meerkat-owned truth.status is completed when a provider-native search event was observed, unavailable when the stream showed none (the search is unverified; any answer is still included and error says so), and failed when the native search call stopped on a refusal, a content filter, a filled context window or a cancellation: error then names the stop and the result has no answer, evidence or native events. A call cut at its output cap (max_tokens) or paused by the provider’s server-tool loop (pause_turn) keeps its status and answer, and error says the answer may be incomplete. This holds since 0.9.4; 0.9.3 and earlier reported a refused search’s text as a completed or unavailable answer.This tool is classified read-only. Visibility is controlled by override_web_search, independently from general builtins.Source: crates/meerkat-tools/src/builtin/web_search.rs

Comms tools

Comms tools enable inter-agent communication. They require the comms Cargo feature (dep:meerkat-comms) and the factory-level enable_comms flag. Unlike other tool categories, comms tools are provided as a separate CommsToolSurface dispatcher (implementing AgentToolDispatcher) and composed via DynamicToolComposite, NOT bundled into CompositeDispatcher. Tool availability is reported per tool through the catalog (comms_tool_unavailable_reason): send_message, reply_to_peer, and peers are advertised even before any peers are configured, while send_request and send_response require a runtime-bound command authority and are otherwise marked unavailable with the typed reason RuntimeCommandAuthorityUnavailable. Tool definitions (name, description, input schema) are dynamically loaded from meerkat_comms::tools_list().
Send a fire-and-forget collaboration message to a trusted peer.Default enabled: Yes (when comms is active)
String
required
Canonical peer ID from the peers tool.
String
Optional display name, retained only for diagnostics.
String
required
Message content.
Array
Optional multimodal blocks: text entries or image_ref entries (source: "current_turn" with index, or source: "blob" with blob_id and media_type).
String
required
Use "queue" for ordinary delivery or "steer" for immediate steer processing on runtime-backed sessions.
Source: crates/meerkat-comms/src/mcp/tools.rs
Reply to a peer message delivered in the current turn, at its start or while it ran. This tool is pre-addressed by a turn-scoped reply capability, so it deliberately has no peer_id argument.Default enabled: Yes when comms is active. It does not require runtime request/response command authority.
String
required
Reply text.
Array
Optional multimodal text or image_ref blocks.
String
required
queue for ordinary delivery or steer for urgent immediate processing.
String
Delivery ID selector: the Delivery ID line of the message notice. Omit when the turn holds exactly one peer message. When several arrived, retry with one ID listed by ambiguous_reply. An id that two senders’ messages share answers ambiguous_reply and sends nothing.
Typed failures include no_reply_capability, ambiguous_reply, and unknown_reply_to. Trust is revalidated at dispatch time, so revoking a peer after turn admission invalidates the previously minted reply capability.Source: crates/meerkat-comms/src/mcp/tools.rs
Send a structured request to a trusted peer. Use when you want explicit intent + params and a correlated response via send_response. Requires a runtime-bound command authority.Default enabled: Yes (when comms is active and runtime command authority is attached)
String
required
Canonical peer ID from the peers tool.
String
Optional display name, retained only for diagnostics.
String
required
Typed request intent: "checksum_token" or "supervisor.bridge". Unknown intents fail at the serde boundary.
Object
required
Request parameters, validated against the selected intent.
Array
Optional multimodal blocks (text and image_ref entries).
String
required
Use "queue" for ordinary delivery or "steer" for immediate steer processing on runtime-backed sessions.
Use send_message for normal agent collaboration. Use send_request only when you want an explicit structured ask and later send_response correlated by in_reply_to.
Only the peer the request was sent to can answer it: the runtime records the addressee’s canonical peer ID before the request leaves, and drops at ingress any response, progress or terminal, signed by another peer’s key (under open auth, require_peer_auth = false, the key the envelope declares). The request stays open for its addressee.Source: crates/meerkat-comms/src/mcp/tools.rs
Send a response to a previously received request from a trusted peer. Requires a runtime-bound command authority.Default enabled: Yes (when comms is active and runtime command authority is attached)
String
required
Canonical peer ID of the peer that sent the request.
String
Optional display name, retained only for diagnostics.
String (UUID)
required
ID of the request being responded to.
String
required
Response status: "accepted", "completed", or "failed".
Object
default:"null"
Typed response payload, validated against the original request contract.
Array
Optional multimodal blocks (text and image_ref entries).
String
Optional override for terminal responses: "queue" or "steer". Forbidden on "accepted" progress responses.
A response, progress or terminal, goes only to the request’s requester: the canonical peer ID of the key that signed the request’s envelope, which the runtime records when the request arrives (under open auth, require_peer_auth = false, the key the envelope declares). A peer_id that is not the requester fails with invalid_arguments and nothing is sent; the request stays open. display_name never changes the addressee. A request ID this session did not receive or has already answered fails with execution_failed, as before.Source: crates/meerkat-comms/src/mcp/tools.rs
List all visible peers with connection info and optional metadata.Returns the runtime peer directory when runtime authority is attached, or a typed view of the trust store otherwise. The current agent is excluded. Names are display labels and may not be unique; use peer_id for sends.Default enabled: Yes (when comms is active)Parameters: None (empty object).
Source: crates/meerkat-comms/src/mcp/tools.rs — PeersInput

Skill tools

The five skill tools are registered only when a SkillRuntime is present. Each has default_enabled: false, so an embedding that constructs the builtin dispatcher must explicitly enable the desired names in BuiltinToolConfig. Current factory-built CLI, REST, and JSON-RPC sessions register the set but do not add that policy enable; preload and typed skill_refs still work, but the interactive skill tools are not advertised there. Every skill identity is a typed pair of source_uuid and skill_name. The runtime canonicalizes source-lineage remaps before reading or invoking it.
browse_skills accepts optional query and source_uuid filters and returns active skills as {source_uuid, skill_name, name, description} entries.load_skill requires source_uuid and skill_name. It resolves and renders the skill, returning the canonical identity, display name, rendered body, and byte_size.Source: crates/meerkat-tools/src/builtin/skills/browse.rs, crates/meerkat-tools/src/builtin/skills/load.rs
skill_list_resources takes source_uuid and skill_name and returns the skill’s artifact descriptors. skill_read_resource adds a required path and returns that artifact’s content.skill_invoke_function takes source_uuid, skill_name, function_name, and optional JSON-object arguments. Its success response echoes the canonical identity and function name and carries the skill function’s wire-opaque JSON in output.Source: crates/meerkat-tools/src/builtin/skills/resources.rs, crates/meerkat-tools/src/builtin/skills/functions.rs

Cargo feature gates

Tool availability depends on compile-time features in the meerkat-tools crate: The memory_search tool is gated by the memory-store-session feature on the meerkat facade crate (not meerkat-tools), since MemorySearchDispatcher lives in meerkat-memory. Source: crates/meerkat-tools/Cargo.toml