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. This page covers enabling tools, per-agent tool settings, function filters, presets, update awareness, and dependency installation. To find a specific tool, see Browse By Topic.

Enabling Tools

List tools under an agent's tools, or under defaults.tools to give them to every agent:

defaults:
  tools:
    - scheduler

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

Each agent gets its own tools plus defaults.tools, without duplicates. The defaults.tools default and the per-agent include_default_tools opt-out are described in Agent Configuration. Configured MCP servers appear as tools named mcp_<server_id>; see MCP. When config_manager or self_config replaces an agent's tool list, tools that stay keep their inline settings.

Per-Agent Tool Configuration

A tool entry can be a plain name or a single-key mapping of the tool name to inline settings. Inline settings change the tool for that agent only. Settings under defaults.tools apply to every agent that includes default tools.

defaults:
  tools:
    - scheduler
    - shell:
        enable_run_shell_command: true     # every agent

agents:
  code:
    tools:
      - filesystem                         # no inline settings
      - shell:                             # this agent only
          extra_env_passthrough: "DAWARICH_*"
  research:
    tools:
      - shell                              # uses the defaults.tools settings
      - duckduckgo

Each tool's page lists the settings it accepts.

Security Restrictions

Some fields cannot be set inline:

  • password fields, such as API keys and tokens, must be set through the dashboard, the credential store, or the environment variables the tool's page names.
  • Fields MindRoom manages itself, such as base_dir, cannot be overridden.
  • Per-agent-only fields, such as the usage_stats tool's admin_scope, are rejected in defaults.tools.

MindRoom rejects these fields, unknown field names, and values of the wrong type when the config loads, and the unknown-field error lists the allowed fields.

How Settings Combine

From lowest to highest priority, a tool's settings come from:

  1. The tool's built-in defaults.
  2. The environment variables its page names, such as TAVILY_API_KEY, read from the process environment, then the .env next to config.yaml, then their _FILE variants.
  3. Saved tool settings from the dashboard or credential store.
  4. defaults.tools inline settings.
  5. agents.<name>.tools inline settings.
  6. Values MindRoom sets for the agent's runtime, such as its workspace directory.

When a tool appears in both defaults.tools and an agent's tools, the settings merge field by field. Per-agent values win for the same field, and fields set in only one place are kept. An empty saved value counts as unset, so the environment variable still applies. A call that runs in a worker rebuilds the tool there from its leased saved settings and the worker's own environment, without the primary's .env secrets, so save a key such a call needs in the dashboard. The dashboard's Tools page counts only saved settings, so it can list a tool that environment variables configure as needing configuration.

Clearing An Inherited Override

Set a field to __MINDROOM_INHERIT__ to keep a tool but drop one inherited defaults.tools setting:

defaults:
  tools:
    - shell:
        extra_env_passthrough: "DAWARICH_*"
        enable_run_shell_command: true

agents:
  research:
    tools:
      - shell:
          extra_env_passthrough: __MINDROOM_INHERIT__

research still inherits enable_run_shell_command: true, while extra_env_passthrough falls back to the saved tool setting, or to the tool's default when none is saved. To drop every default tool and all their settings for an agent instead, set include_default_tools: false.

Filtering Toolkit Functions

Most built-in toolkits accept include_tools and exclude_tools inline settings to limit which of their functions the agent sees. include_tools is an allowlist, and exclude_tools removes functions from what remains. Use the function names the toolkit exposes. Tools that do not support filtering reject these fields when the config loads.

agents:
  research:
    tools:
      - searxng:
          include_tools:
            - search_web
            - news_search
            - image_search

A name the toolkit does not provide fails when the tool loads with Included tool(s) not present in the toolkit: <names> or Excluded tool(s) not present in the toolkit: <names>. The built-in usage instructions that daytona, gmail, google_calendar, reasoning, and zep add to the agent's prompt are left out while a function they name is disabled or filtered out; instructions you set through a tool's instructions option are always included.

Browse By Topic

  • Execution & Coding - Local files, shell, Python, coding helpers, and worker-routed execution tools.
  • Background Python Scripts - Long-running Python scripts that call the agent's tools and wake it when something changes.
  • Worker Computer - A visible browser in the agent's worker that the user can watch and control.
  • Desktop Bridge - Operate allowlisted apps, read selected folders, and run approved commands on a local computer.
  • Minimal Agent Mode - One Bash tool instead of full tool schemas, to cut tokens per request.
  • 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, Google Scholar, 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, snoozing, moves, summaries, stopping other agents' replies, model overrides, low-level Matrix API access, a personal agent reading Matrix as its owner, and attachment-aware workflows.
  • Matrix Message Tool - Send, read, edit, and react to messages with matrix_message.
  • Agent Chat UI Actions - Bounded requests to reveal an agent computer, open Settings, open Members, or show an interactive canvas in MindRoom Chat.
  • Messaging & Social - Email, chat, and social/community integrations.
  • Project Management - Git hosting, issue trackers, docs platforms, per-thread work plans, and task managers.
  • Atlassian Cloud - Per-user OAuth Jira and Confluence Cloud access, additional connected sites, and attachment downloads.
  • Slack - Per-user OAuth Slack search, reading, posting, and downloads, project agents that answer mentions of the MindRoom app, and watches that forward a person's Slack mentions and direct messages to Matrix.
  • Microsoft 365 - Per-user OAuth OneDrive and SharePoint files, Excel ranges, SharePoint lists and pages, Outlook mail and calendars, To Do tasks, Teams channels and chats, Teams meeting transcripts, OneNote pages, and the people directory through Microsoft Graph.
  • Calendar & Scheduling - Calendar and task APIs and MindRoom scheduling tools.
  • Memory & Storage - Mem0 and Zep external memory services; the built-in memory tool is documented with the memory system.
  • Agent Orchestration - Delegation, Dynamic Workflows, report publishing, config tools, and Claude Agent sessions.
  • Dynamic Tools - Keep rarely used tools out of the model's context until the agent searches for them.
  • Automation & Platforms - Infrastructure automation, generic APIs, and platform aggregators.
  • Location, Commerce, & Home - Maps, weather, commerce, and Home Assistant.

Tool Presets And Implied Tools

openclaw_compat is a preset that expands to a bundle of MindRoom tools; see OpenClaw Workspace Import. Enabling matrix_message also enables its companion tools.

MindRoom Update Awareness

Enable the update_awareness tool to tell the agent which MindRoom version is installed and which release is the latest on PyPI.

defaults:
  tools:
    - update_awareness

MindRoom checks PyPI at most once every 24 hours and caches the result in mindroom_data/cache/update_awareness.json. When a newer release exists, the agent mentions it briefly at a natural moment, once per conversation, and does not install it unless the user asks. The agent can also call get_mindroom_update_status() to report both versions.

Automatic Dependency Installation

When an enabled tool's optional Python dependencies are missing, MindRoom installs them the first time the tool loads. Set MINDROOM_NO_AUTO_INSTALL_TOOLS=1 to disable this. When auto-install is disabled or fails, the tool fails to load with Missing dependencies for tool '<tool>': <packages>. An installed dependency at a version its extra does not allow, such as one an older MindRoom installed, counts as missing; when it cannot be installed again, loading fails with Unsupported dependency versions: <package> <version> (needs <requirement>). Install the tool's extra manually, for example pip install 'mindroom[<tool>]' or uv sync --extra <tool> in a source checkout.

  • MCP - Configure native MCP client servers and expose them as MindRoom tools.
  • Plugins - Extend MindRoom with custom tools and skills.
  • Sandbox Proxy - Which tools run in isolated workers and which stay in the primary runtime.
  • OAuth Onboarding In Conversation - How agents send users links to connect OAuth tools.
  • Attachments - Attachment lifecycle and context scoping.
  • Scheduling - Chat command scheduling and task behavior.