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.

MindRoom-Managed OAuth Onboarding In Conversation

This flow applies to tools whose MindRoom catalog metadata names an auth_provider, including the Google provider tools and OAuth MCP servers. It does not apply to every tool labeled SetupType.OAUTH; tools without auth_provider metadata use their own setup contract. When config_manager creates or updates an agent with one of these tools, it returns a connect URL scoped to the updated agent and current authorized requester when that binding is available. Present that URL directly instead of asking the configuring agent to call the new tool, because newly configured tools are not guaranteed to enter the current run's tool schema. When the current agent already has a MindRoom-managed provider tool, call an appropriate safe status, read, or list operation to check its connection. For an OAuth MCP server, use its generated *_connection_status or *_list_tools operation. If the operation is disconnected, its structured OAuthConnectionRequired result includes oauth_connection_required: true, a scoped connect_url when available, and requires_host_browser: true when the URL uses a supported loopback host. When connect_url is provided, present it directly instead of sending the user to the dashboard. When requires_host_browser is true, explain that the loopback URL (localhost, 127.0.0.1, or ::1) must be opened in a browser on the computer where MindRoom is running, not on a phone or another computer. After the user connects, have the target agent retry the safe operation or original request. The dashboard remains a manual alternative only when no connect_url is available.

Browse By Topic

Execution & Coding - Local files, shell, Python, coding helpers, and worker-routed execution tools.
Data & Databases - SQL, databases, Google Docs and Drive files, spreadsheets, tabular analysis, and financial/business datasets.
Web Search - Search engines and search APIs.
Web Scraping & Browser - Crawlers, extractors, browser automation, and page-reading tools.
Research Sources - ArXiv, Wikipedia, PubMed, and Hacker News.
AI & Generation - Image, video, speech, and transcription APIs.
Media & Content - Media processing, brand/media retrieval, and Spotify.
Matrix & Attachments - Matrix-native messaging and voice messages, thread tags, resolution, summaries, and model overrides, low-level Matrix API access, and attachment-aware workflows.
Messaging & Social - Email, chat, and social/community integrations.
Project Management - Git hosting, issue trackers, docs platforms, per-thread work plans, and task managers.
Calendar & Scheduling - Calendar APIs and MindRoom scheduling tools.
Memory & Storage - Explicit memory tools and external memory providers.
Agent Orchestration - OAuth connection recovery, subagents, delegation, Dynamic Workflows, config tools, OpenClaw compatibility, and Claude Agent sessions.
Dynamic Tools - Per-tool lazy loading for optional agent capabilities.
Automation & Platforms - Infrastructure automation, generic APIs, and platform aggregators.
Location, Commerce, & Home - Maps, weather, commerce, and Home Assistant.

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 both attachments and matrix_room, so the effective tool set includes all three 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, thread_resolution, 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.list_thread_tags(exclude_tag="resolved", include_untagged=True) lists unresolved room threads, including threads that have no tag state yet. include_untagged=True forces a room-wide query and cannot be combined with thread_id. It enumerates Matrix /threads and may stop at the 2000-root safety cap. The response includes include_untagged: bool and truncated: bool. Callers must check truncated before claiming the unresolved list is complete. 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_resolution is an explicit opt-in capability backed by the resolved thread tag and does not read the removed experimental com.mindroom.thread.resolution event type. It is absent from starter configs and default tool sets, while thread_tags can list but cannot mutate resolved state. 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".

MindRoom Update Awareness

Enable the update_awareness tool to add the installed MindRoom version and the latest published PyPI release to the agent's system prompt. The tool checks PyPI at most once every 24 hours and stores the result under mindroom_data/cache/update_awareness.json. Every prompt assembled during that cache window receives identical version text, so ordinary turns do not invalidate the prompt cache. When a newer release is available, the agent is instructed to notify the user briefly at a natural opportunity without repeating the notice in the same conversation.

defaults:
  tools:
    - update_awareness

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, coding, and docker. 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 and homeassistant. MCP mcp_<server_id> tools work on every worker scope: OAuth credentials and sessions follow the selected agent's effective execution scope, while non-OAuth servers always call through the shared server session without requester credentials. For OAuth-backed MCP, shared belongs to the agent, user belongs to the requester across agents, user_agent belongs to one requester-agent pair, and unscoped belongs to the installation.

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.