Built-in tools reference

Overview

Tool	Category	Default	Gate	Description
`task_create`	Task	Yes	—	Create a new task
`task_get`	Task	Yes	—	Get a task by ID
`task_list`	Task	Yes	—	List tasks with optional filters
`task_update`	Task	Yes	—	Update an existing task
`shell`	Shell	No	—	Execute a shell command
`shell_jobs`	Shell	No	—	List background shell jobs
`shell_job_status`	Shell	No	—	Check background job status
`shell_job_cancel`	Shell	No	—	Cancel a background job
`memory_search`	Memory	N/A	`memory-store-session`	Search semantic memory
`wait`	Utility	Yes	—	Pause execution
`datetime`	Utility	Yes	—	Get current date/time
`apply_patch`	Utility	Yes	—	Apply structured file patches inside the project root
`view_image`	Utility	Yes	vision	Read an image file and return base64 content
`send`	Comms	Yes	`comms`	Send message/request/response to a peer
`peers`	Comms	Yes	`comms`	List discoverable peers (trusted + inproc)

Enabling and disabling tools

Factory-level flags

AgentFactory controls which tool categories are available via builder methods:

Flag	Builder Method	Default	Controls
`enable_builtins`	`.builtins(bool)`	`false`	Task tools, utility tools (`wait`, `datetime`, `apply_patch`)
`enable_shell`	`.shell(bool)`	`false`	All shell tools (`shell`, `shell_jobs`, `shell_job_status`, `shell_job_cancel`)
`enable_memory`	`.memory(bool)`	`false`	`memory_search` (requires `memory-store-session` feature)
`enable_comms`	`.comms(bool)`	`false`	All comms tools (requires `comms` feature)
`enable_mob`	`.mob(bool)`	`false`	Mob orchestration tools (`mob_`, `meerkat_`)

AgentFactory is the only place tool categories are composed. AgentBuilder (in meerkat-core) has no dependency on meerkat-tools and does not auto-register any tools — it takes a pre-built dispatcher. See AgentBuilder vs AgentFactory.Source: meerkat/src/factory.rs — AgentFactory struct and builder methods.

Per-build overrides

Each AgentBuildConfig can override factory-level flags for a single agent build:

Override Field	Type	Effect
`override_builtins`	`Option<bool>`	Takes precedence over `enable_builtins` when `Some`
`override_shell`	`Option<bool>`	Takes precedence over `enable_shell` when `Some`
`override_memory`	`Option<bool>`	Takes precedence over `enable_memory` when `Some`
`override_mob`	`Option<bool>`	Takes precedence over `enable_mob` when `Some`

All default to None (use factory-level setting).Source: meerkat/src/factory.rs — AgentBuildConfig struct.

ToolPolicyLayer

Individual tools can be enabled or disabled via ToolPolicyLayer in BuiltinToolConfig. When shell is enabled, a ToolPolicyLayer is applied that activates the four shell tools (which have default_enabled: false).

Capability registrations

Capabilities are registered via the inventory crate in meerkat-tools/src/lib.rs:

Builtins (CapabilityId::Builtins): task_list, task_create, task_get, task_update, wait, datetime, apply_patch, view_image. Controlled by config.tools.builtins_enabled.
Shell (CapabilityId::Shell): shell, shell_jobs, shell_job_status, shell_job_cancel. Controlled by config.tools.shell_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 lifecycle

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 [SYSTEM NOTICE] is injected into 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: meerkat-core/src/tool_scope.rs

Live MCP server mutation

MCP servers can be added or removed from a running session. Operations are staged on the McpRouter and applied at the next turn boundary.

Surface	Method	Status
JSON-RPC	`mcp/add`, `mcp/remove`, `mcp/reload`	Fully wired (staged)
REST	`POST /sessions/{id}/mcp/add\|remove\|reload`	Routes registered (placeholder)
CLI	`rkat mcp add/remove --session <id> --live-server-url <url>`	Delegates to REST

Servers being removed transition through Active → Removing (draining) → Removed to allow in-flight tool calls to complete before finalization.Source: meerkat-mcp/src/router.rs, meerkat-rpc/src/handlers/mcp.rs

Per-turn flow tool overlay

Mob flow steps can restrict tools for a single turn via TurnToolOverlay:

TurnToolOverlay {
    allowed_tools: Option<Vec<String>>,  // allow-list for this turn
    blocked_tools: Option<Vec<String>>,  // deny-list for this turn
}

Set on StartTurnRequest.flow_tool_overlay by the flow engine. Ephemeral — cleared after the turn completes. Composes with the external filter using most-restrictive semantics.Source: meerkat-core/src/service/mod.rs, meerkat-mob/src/runtime/flow.rs

Task tools

Task tools provide structured work tracking. They are enabled by default when builtins are on. Tasks are persisted via TaskStore (either FileTaskStore on disk or MemoryTaskStore in-memory).

Task data model

A Task object returned by task tools has these fields:

Field	Type	Description
`id`	`String`	Unique task identifier
`subject`	`String`	Short subject/title
`description`	`String`	Detailed description
`status`	`String`	`"pending"`, `"in_progress"`, or `"completed"`
`priority`	`String`	`"low"`, `"medium"`, or `"high"`
`labels`	`String[]`	Labels/tags for categorization
`blocks`	`String[]`	IDs of tasks that this task blocks
`blocked_by`	`String[]`	IDs of tasks that block this task
`created_at`	`String`	ISO 8601 creation timestamp
`updated_at`	`String`	ISO 8601 last-updated timestamp
`created_by_session`	`String?`	Session ID that created this task
`updated_by_session`	`String?`	Session ID that last updated this task
`owner`	`String?`	Owner/assignee (agent name or user identifier)
`metadata`	`Object`	Arbitrary key-value metadata

Source: meerkat-tools/src/builtin/types.rs — Task struct.

task_create

Create a new task in the project task list.Default enabled: Yes

subject

String

required

Short subject/title of the task.

description

String

required

Detailed description of what needs to be done.

priority

String

default:"medium"

"low", "medium", or "high".

labels

String[]

default:"[]"

Labels/tags for categorization.

blocks

String[]

default:"[]"

Task IDs that this task blocks.

blocked_by

String[]

default:"[]"

Task IDs that block this task.

owner

String

default:"null"

Owner/assignee.

metadata

Object

default:"{}"

Arbitrary key-value metadata.

Returns: The created Task object (see task data model above).Source: meerkat-tools/src/builtin/tasks/task_create.rs

task_get

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: meerkat-tools/src/builtin/tasks/task_get.rs

task_list

List tasks in the project, optionally filtered by status or labels.Default enabled: Yes

status

String

default:"null (all)"

Filter by status: "pending", "in_progress", or "completed".

labels

String[]

default:"null (all)"

Filter by labels (tasks matching any label).

Returns: Array of Task objects matching the filters.Source: meerkat-tools/src/builtin/tasks/task_list.rs

task_update

Update an existing task. Only provided fields are modified; omitted fields remain unchanged.Default enabled: Yes

String

required

The task ID to update.

subject

String

default:"unchanged"

New subject/title.

description

String

default:"unchanged"

New description.

status

String

default:"unchanged"

New status: "pending", "in_progress", or "completed".

priority

String

default:"unchanged"

New priority: "low", "medium", or "high".

labels

String[]

default:"unchanged"

Replace all labels.

owner

String

default:"unchanged"

New owner/assignee.

metadata

Object

default:"unchanged"

Merge metadata (set key to null to remove).

add_blocks

String[]

default:"[]"

Task IDs to add to the blocks list.

remove_blocks

String[]

default:"[]"

Task IDs to remove from the blocks list.

add_blocked_by

String[]

default:"[]"

Task IDs to add to the blocked_by list.

remove_blocked_by

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: meerkat-tools/src/builtin/tasks/task_update.rs

Shell tools

Shell tools execute commands and manage background jobs. They are all default_enabled: false and require the factory-level enable_shell flag (or a ToolPolicyLayer override) to be active.

Shell configuration

Shell behavior is controlled by ShellConfig:

Config Field	Type	Default	Description
`enabled`	`bool`	`false`	Master switch for shell tools
`default_timeout_secs`	`u64`	`30`	Default command timeout
`restrict_to_project`	`bool`	`true`	Restrict working dirs to project root
`shell`	`String`	`"nu"`	Shell binary name (Nushell by default; falls back to bash/zsh/sh)
`shell_path`	`PathBuf?`	`None`	Explicit shell binary path
`project_root`	`PathBuf`	CWD	Project root for path restriction
`max_completed_jobs`	`usize`	`100`	Maximum completed jobs retained
`completed_job_ttl_secs`	`u64`	`300`	TTL for completed job records (seconds)
`max_concurrent_processes`	`usize`	`10`	Maximum concurrent background processes
`security_mode`	`SecurityMode`	`Unrestricted`	Command security policy
`security_patterns`	`Vec<String>`	`[]`	Glob patterns for allow/deny lists

Source: meerkat-tools/src/builtin/shell/config.rs

Shell security modes

The SecurityEngine validates commands before execution using POSIX-compliant word splitting (shlex) and glob pattern matching (globset).

Mode	Behavior
`Unrestricted`	All commands allowed (default)
`AllowList`	Only commands matching `security_patterns` globs are allowed
`DenyList`	Commands matching `security_patterns` globs are rejected

Patterns are matched against the canonicalized command invocation. The engine parses the full command string into individual words, then validates the executable (first word) and the full command string against the pattern set.Source: meerkat-tools/src/builtin/shell/security.rs

shell

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)

command

String

required

The command to execute (POSIX-style parsing for policy checks).

working_dir

String

default:"Project root"

Working directory (relative to project root).

timeout_secs

u64

default:"Config default (30)"

Timeout in seconds.

background

bool

default:"false"

If true, run in background and return job ID immediately.

{
  "exit_code": 0,
  "stdout": "...",
  "stderr": "...",
  "timed_out": false,
  "duration_secs": 1.23
}

Output is truncated to the last 100,000 characters if it exceeds that limit. Fields stdout_lossy and stderr_lossy indicate whether output was lossy-decoded from non-UTF-8 bytes.

Source: meerkat-tools/src/builtin/shell/tool.rs

shell_jobs

List all background shell jobs.Default enabled: No (requires shell to be enabled)Parameters: None (empty object).

[
  {
    "id": "job_<uuid-v7>",
    "command": "echo hello",
    "status": "running",
    "started_at_unix": 1700000000
  }
]

The status field is one of: "running", "completed", "failed", "timed_out", "cancelled".Source: meerkat-tools/src/builtin/shell/jobs_list_tool.rs

shell_job_status

Check status of a background shell job. Returns full job details including output when complete.Default enabled: No (requires shell to be enabled)

job_id

String

required

The job ID to check.

{
  "id": "job_<uuid-v7>",
  "command": "echo test",
  "working_dir": "/path/to/project",
  "timeout_secs": 30,
  "started_at_unix": 1700000000,
  "status": "completed"
}

Error: ExecutionFailed if the job ID is not found.Source: meerkat-tools/src/builtin/shell/job_status_tool.rs

shell_job_cancel

Cancel a running background shell job.Default enabled: No (requires shell to be enabled)

job_id

String

required

The job ID to cancel.

{
  "job_id": "job_<uuid-v7>",
  "status": "cancelled"
}

Error: ExecutionFailed if the job ID is not found.Source: meerkat-tools/src/builtin/shell/job_cancel_tool.rs

Shell types

JobId format: "job_" followed by a UUID v7 string.JobStatus variants: Running, Completed, Failed, TimedOut, Cancelled (serialized as lowercase snake_case strings).Source: 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.

memory_search

Search semantic memory for past conversation content. Memory contains text from earlier conversation turns that were compacted away to save context space.

query

String

required

Natural language search query describing what you want to recall.

limit

usize

default:"5"

Maximum number of results to return (max: 20).

The limit is capped at 20 regardless of the requested value.

[
  {
    "content": "The project codename is AURORA-7",
    "score": 0.87,
    "session_id": "<uuid>",
    "turn": 3
  }
]

Returns an empty array if no matches are found.Source: meerkat-memory/src/tool.rs

Utility tools

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

wait

Pause execution for the specified number of seconds. Supports fractional seconds. Useful for polling loops or rate limiting.Default enabled: Yes

seconds

f64

required

Duration to wait in seconds (clamped to 0.0 to 60.0).

Maximum wait time is 60 seconds (1 minute). Values are clamped to the range 0.0 to 60.0.

{
  "waited_seconds": 5.0,
  "status": "complete"
}

Source: meerkat-tools/src/builtin/utility/wait.rs

datetime

Get the current date and time. Returns ISO 8601 formatted datetime and Unix timestamp.Default enabled: YesParameters: None (empty object).

{
  "iso8601": "2025-01-15T14:30:00+01:00",
  "date": "2025-01-15",
  "time": "14:30:00",
  "timezone": "+01:00",
  "unix_timestamp": 1736949000,
  "year": 2025,
  "month": 1,
  "day": 15,
  "weekday": "Wednesday"
}

Source: meerkat-tools/src/builtin/utility/datetime.rs

view_image

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 model supports vision)

path

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 automatically hidden via ToolScope when the active model does not support vision (i.e., ModelProfile.vision == false). It is also hidden when the model does not support image content in tool results (ModelProfile.image_tool_results == false). This means the tool never appears in the tool list sent to models that cannot process image content.Returns: A ToolOutput::Blocks containing a single ContentBlock::Image with the base64-encoded image data and detected media type. The source_path field is set on the domain type but stripped from the wire representation (WireContentBlock).Source: meerkat-tools/src/builtin/utility/view_image.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 ToolGateway, NOT bundled into CompositeDispatcher. Comms tools are only shown to the agent when at least one peer is discoverable (controlled by CommsToolSurface::peer_availability()). The check passes when TrustedPeers has entries. Tool definitions (name, description, input schema) are dynamically loaded from meerkat_comms::tools_list().

send

Send a message, request, or response to a trusted peer. The kind parameter determines the message type.Default enabled: Yes (when comms is active)

String

required

Peer name to send to.

kind

String

required

Message kind: "peer_message", "peer_request", or "peer_response".

body

String

Message content (required when kind="peer_message").

intent

String

Request intent/action identifier (required when kind="peer_request").

params

any

default:"null"

Request parameters (for kind="peer_request").

in_reply_to

String (UUID)

ID of the request being responded to (required when kind="peer_response").

status

String

Response status: "accepted", "completed", or "failed" (required when kind="peer_response").

result

any

default:"null"

Response result data (for kind="peer_response").

{
  "status": "sent",
  "kind": "peer_message"
}

Source: meerkat-comms/src/mcp/tools.rs — SendInput

peers

List all discoverable peers and their connection status.Returns configured trusted peers (TrustedPeers), excluding the current agent (“self”) by public key.Default enabled: Yes (when comms is active)Parameters: None (empty object).

{
  "peers": [
    {
      "name": "agent-beta",
      "peer_id": "<derived-peer-id>",
      "address": "tcp://127.0.0.1:4200"
    }
  ]
}

Source: meerkat-comms/src/mcp/tools.rs — PeersInput

Cargo feature gates

Tool availability depends on compile-time features in the meerkat-tools crate:

Feature	Default	Dependencies	Tools unlocked
`comms`	Yes	`dep:meerkat-comms`	`send`, `peers`
`mcp`	Yes	`dep:meerkat-mcp`	External MCP tool routing (not builtin tools)

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: meerkat-tools/Cargo.toml

Reference

Architecture

Built-in tools reference

Overview

Enabling and disabling tools

Runtime tool scoping

Task tools

Shell tools

Memory tool

Utility tools

Comms tools

Cargo feature gates

Reference

Architecture

​Overview

​Enabling and disabling tools

​Runtime tool scoping

​Task tools

​Shell tools

​Memory tool

​Utility tools

​Comms tools

​Cargo feature gates

Overview

Enabling and disabling tools

Runtime tool scoping

Task tools

Shell tools

Memory tool

Utility tools

Comms tools

Cargo feature gates