Built-in tools reference

Comprehensive reference for all built-in tools available in Meerkat, including parameters, types, and defaults.

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
agent_spawn	Sub-Agent	No	sub-agents	Spawn a new sub-agent
agent_fork	Sub-Agent	No	sub-agents	Fork with continued context
agent_status	Sub-Agent	No	sub-agents	Get sub-agent status
agent_cancel	Sub-Agent	No	sub-agents	Cancel a sub-agent
agent_list	Sub-Agent	No	sub-agents	List all sub-agents
memory_search	Memory	N/A	memory-store-session	Search semantic memory
wait	Utility	Yes	—	Pause execution
datetime	Utility	Yes	—	Get current date/time
send_message	Comms	Yes	comms	Send text to a peer
send_request	Comms	Yes	comms	Send a request to a peer
send_response	Comms	Yes	comms	Respond to a request
list_peers	Comms	Yes	comms	List trusted peers

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)
enable_shell	.shell(bool)	false	All shell tools (shell, shell_jobs, shell_job_status, shell_job_cancel)
enable_subagents	.subagents(bool)	false	All sub-agent tools (requires sub-agents feature)
enable_memory	.memory(bool)	false	memory_search (requires memory-store-session feature)
enable_comms	.comms(bool)	false	All comms tools (requires comms feature)

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_subagents	Option<bool>	Takes precedence over enable_subagents when Some
override_memory	Option<bool>	Takes precedence over enable_memory 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). The same mechanism applies to sub-agent tools.

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. Controlled by config.tools.builtins_enabled.
• Shell (CapabilityId::Shell): shell, shell_jobs, shell_job_status, shell_job_cancel. Controlled by config.tools.shell_enabled.
• SubAgents (CapabilityId::SubAgents): agent_spawn, agent_fork, agent_status, agent_cancel, agent_list. Requires sub-agents feature.

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

id · 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

id · 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.

Returns (foreground)

{
  "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

Sub-agent tools

Sub-agent tools allow spawning, forking, monitoring, and cancelling child agents. They are all default_enabled: false and require both the sub-agents Cargo feature and the factory-level enable_subagents flag.

Shared types

ToolAccessInput (tagged union, "policy" discriminator):

Variant	Fields	Description
inherit	—	Inherit all tools from parent
allow_list	tools: String[]	Only allow the listed tools
deny_list	tools: String[]	Block the listed tools

Example: {"policy": "allow_list", "tools": ["shell", "task_list"]}

BudgetInput (used in agent_spawn):

Field	Type	Required	Description
max_tokens	u64	No	Maximum tokens for the sub-agent
max_turns	u32	No	Maximum turns for the sub-agent
max_tool_calls	u32	No	Maximum tool calls for the sub-agent

agent_spawn

Spawn a new sub-agent with clean context. The sub-agent starts fresh with only the provided prompt.

Default enabled: No (requires sub-agents feature + subagents enabled)

prompt · String · required

Initial prompt/task for the sub-agent.

provider · String · default: "Parent's provider"

LLM provider: "anthropic", "openai", or "gemini".

model · String · default: "Provider's default"

Model name (provider-specific).

tool_access · ToolAccessInput · default: "inherit"

Tool access policy (see shared types).

budget · BudgetInput · default: "Inherited"

Budget limits (see shared types).

system_prompt · String · default: "null"

Override system prompt for the sub-agent.

host_mode · bool · default: "false"

Agent stays alive processing comms after initial prompt (only with comms feature).

The host_mode parameter is only present when the comms feature is enabled. Without comms, SpawnParamsNoComms is used which omits this field.

{
  "agent_id": "<uuid>",
  "name": "agent-<name>",
  "provider": "anthropic",
  "model": "claude-sonnet-4-5",
  "state": "running",
  "message": "Sub-agent spawned successfully"
}

When comms is enabled and host_mode is active, additional comms field is included with connection details.

Source: meerkat-tools/src/builtin/sub_agent/spawn.rs

agent_fork

Fork the current agent with continued context. The forked agent inherits the parent’s conversation history.

Default enabled: No (requires sub-agents feature + subagents enabled)

prompt · String · required

Additional prompt/instruction appended to inherited conversation history.

provider · String · default: "Parent's provider"

"anthropic", "openai", or "gemini".

model · String · default: "Provider's default"

Model name (provider-specific).

tool_access · ToolAccessInput · default: "inherit"

Tool access policy (see shared types).

budget_policy · String · default: "null"

Budget allocation: "equal", "remaining", "proportional", or "fixed:N".

{
  "agent_id": "<uuid>",
  "name": "fork-<name>",
  "provider": "anthropic",
  "model": "claude-sonnet-4-5",
  "state": "running",
  "messages_inherited": 12,
  "message": "Agent forked successfully"
}

Source: meerkat-tools/src/builtin/sub_agent/fork.rs

agent_status

Get status and output of a sub-agent by ID. Use this to poll for completion.

Default enabled: No (requires sub-agents feature + subagents enabled)

agent_id · String · required

UUID of the sub-agent.

{
  "agent_id": "<uuid>",
  "state": "completed",
  "output": "The agent's final text output",
  "is_final": true,
  "duration_ms": 5432,
  "tokens_used": 1500
}

When the agent is still running, is_final is false and output/duration_ms/tokens_used may be absent. If the agent failed, an error field is present instead of output.

Source: meerkat-tools/src/builtin/sub_agent/status.rs

agent_cancel

Cancel a running sub-agent.

Default enabled: No (requires sub-agents feature + subagents enabled)

agent_id · String · required

UUID of the sub-agent to cancel.

{
  "agent_id": "<uuid>",
  "success": true,
  "previous_state": "running",
  "message": "Agent cancelled"
}

Source: meerkat-tools/src/builtin/sub_agent/cancel.rs

agent_list

List all sub-agents spawned by this agent.

Default enabled: No (requires sub-agents feature + subagents enabled)

Parameters: None (empty object).

{
  "agents": [
    {
      "id": "<uuid>",
      "name": "agent-<name>",
      "state": "running",
      "depth": 1,
      "running_ms": 3200
    }
  ],
  "running_count": 1,
  "completed_count": 0,
  "failed_count": 0,
  "total_count": 1
}

Source: meerkat-tools/src/builtin/sub_agent/list.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 (range: 0.1 to 300.0).

Maximum wait time is 300 seconds (5 minutes). Values below 0.1 or above 300.0 are rejected.

Returns (completed)

{
  "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: Yes

Parameters: 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

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 trusted peer is configured (controlled by CommsToolSurface::peer_availability()).

Tool definitions (name, description, input schema) are dynamically loaded from meerkat_comms::tools_list().

send_message

Send a simple text message to a trusted peer. The peer receives it in their inbox.

Default enabled: Yes (when comms is active)

to · String · required

Peer name to send the message to.

body · String · required

Message content.

{
  "status": "sent"
}

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

send_request

Send a request to a trusted peer and wait for acknowledgement. Use this for structured interactions where you expect a response.

Default enabled: Yes (when comms is active)

to · String · required

Peer name to send the request to.

intent · String · required

Request intent/action identifier.

params · any · default: "null"

Request parameters (arbitrary JSON).

{
  "status": "sent"
}

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

send_response

Send a response back to a previous request from a peer.

Default enabled: Yes (when comms is active)

to · String · required

Peer name to send the response to.

in_reply_to · String (UUID) · required

ID of the request being responded to.

status · String · required

Response status: "accepted", "completed", or "failed".

result · any · default: "null"

Response result data (arbitrary JSON).

{
  "status": "sent"
}

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

list_peers

List all trusted peers and their connection status.

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 — ListPeersInput

Cargo feature gates

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

Feature	Default	Dependencies	Tools unlocked
sub-agents	Yes	dep:meerkat-client	agent_spawn, agent_fork, agent_status, agent_cancel, agent_list
comms	Yes	dep:meerkat-comms	send_message, send_request, send_response, list_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