Skip to content

Tools

MindRoom includes 100+ built-in tools and presets that agents can use to work with files, services, external APIs, and Matrix-native workflows.

Enabling Tools

Tools are enabled per-agent in the configuration. Each tool entry can be a plain string or a single-key dict with inline config overrides:

agents:
  assistant:
    display_name: Assistant
    role: A helpful assistant with file and web access
    model: sonnet
    tools:
      - file
      - shell:
          extra_env_passthrough: "DAWARICH_*"
      - github
      - duckduckgo

You can also assign tools to all agents globally:

defaults:
  tools:
    - scheduler

defaults.tools are merged into each agent's own tools list with duplicates removed. Set defaults.tools: [] to disable global default tools, or set agents.<name>.include_default_tools: false to opt out a specific agent. When the same tool appears in both defaults.tools and an agent's tools with inline overrides, the per-agent overrides take priority, with non-overlapping keys merged from both. See Per-Agent Tool Configuration for the full override syntax and merge order. Configured MCP servers also appear here as dynamic tools named mcp_<server_id>. See MCP for the mcp_servers config and naming rules.

Browse By Topic

Tool Presets And Implied Tools

Some entries are config-only presets rather than runtime toolkits. openclaw_compat expands to a native bundle of MindRoom tools. Some tools also imply companion tools through Config.IMPLIED_TOOLS. Today matrix_message implies attachments, so the effective tool set includes both even when only matrix_message is configured explicitly.

Tool Runtime Context

When a tool runs inside a Matrix-connected agent, it receives a ToolRuntimeContext via a context variable. This context carries the current room_id, source thread_id, canonical resolved_thread_id, requester_id, agent_name, the Matrix client, the active config, and runtime paths. thread_id preserves the raw inbound thread provenance, while resolved_thread_id is the canonical thread scope after compatible plain replies and other transitive resolution are applied. Tools like matrix_message, matrix_room, thread_tags, and matrix_api use this context to act on the correct room and canonical thread without the caller passing explicit IDs. thread_tags can also target another authorized room, but it still checks the target room's canonical thread root and requester membership before writing the shared tag state. thread_tags.tag_thread() and thread_tags.untag_thread() still use the active thread when the caller explicitly repeats the current room_id. thread_tags.list_thread_tags() uses the active thread by default, but passing room_id without thread_id forces room-wide listing even from inside an active thread. thread_tags.list_thread_tags(tag=...) narrows both thread-specific and room-wide responses to the requested tag only. thread_tags.list_thread_tags(include_tag=..., exclude_tag=...) filters which threads are returned: include_tag keeps only threads with that tag, exclude_tag removes threads with that tag. Both can be combined. Unlike tag (which narrows the output payload), these filter which threads appear at all. thread_tags also validates and normalizes predefined payload schemas for blocked.data.blocked_by, waiting.data.waiting_on, priority.data.level, and due.data.deadline. thread_tags intentionally replaces the removed experimental thread_resolution tool and does not auto-read old com.mindroom.thread.resolution markers. matrix_api defaults room_id to the active room, supports authorized cross-room targeting, never infers event IDs or state keys from thread context, and now also supports room-scoped full-text search through action="search".

Worker-Routed Execution

Some tools default to running in a sandboxed worker container instead of the primary agent process. The current worker-routed defaults are file, shell, python, and coding. Use Sandbox Proxy Isolation for deployment details and worker-scope behavior.

Shared-Only Integrations

Some dashboard integrations are restricted to shared or unscoped execution and cannot be used by agents with isolating worker scopes. The current shared-only integrations are spotify, homeassistant, and all configured mcp_<server_id> tools.

Automatic Dependency Installation

Each tool declares its optional Python dependencies in pyproject.toml. When a tool is enabled but its dependencies are missing, MindRoom can auto-install the required extra at runtime. Set MINDROOM_NO_AUTO_INSTALL_TOOLS=1 to disable that behavior.

  • MCP - Configure native MCP client servers and expose them as MindRoom tools.
  • Plugins - Extend MindRoom with custom tools and skills.
  • Attachments - Attachment lifecycle and context scoping.
  • Scheduling - Chat command scheduling and task behavior.
  • OpenClaw Workspace Import - openclaw_compat preset and workspace portability.