Built-in tools

Tools are the capabilities you grant to an agent. Most ship in a mc-agent-tools-* module and register via the ToolFactory SPI — add the module to the runtime and the tool is available to assign. Some live in mc-agent-runtime-core itself (the todo tools, tool_search, skill, and the inline run_agent/run_agents), and dynamic bundles like Gmail or workflow tools use the second SPI, MultiToolProvider. This page lists the built-in tools, what they do, and any configuration or environment keys they need.

Most tools need no configuration. The ones that do are called out in the Needs column; environment variables are documented on the environment variables page.

Core tools (mc-agent-tools)

Always available; no API keys required.

Tool	Description	Needs
get_current_datetime	Returns the current date and time in the user's time zone, in ISO-8601 with the offset and the zone id (2026-09-24T17:36:05+02:00[Europe/Zurich]).	—
list_agents	Lists the agents this one may call, with their names and descriptions. Added by the runtime with run_agent.	—
bash	Runs a bash command in the session's working directory; output drained as it comes, capped at 30,000 characters; timeout per call (default 120 s, max 600); a timed-out or cancelled command is killed with everything it spawned. background starts a server or watcher detached, watches it for three seconds and returns its pid, whether it is still running or already exited with which code, the log so far, and the log file (logs/ in the session's directory).	Working dir
process_list	Lists the background processes of this session: pid, running or exited, command and log file. Read-only.	—
process_kill	Ends a background process of this session by pid, with everything it spawned (without a pid it still lists them, as process_list does). Whatever still runs when the runtime stops is killed with it.	—
file_read	Reads a text file with numbered lines, cat -n style; offset and limit page through a long one (2,000 lines or 20,000 characters per call); refuses binary files.	Working dir
file_edit	Replaces one exact passage (old_string → new_string, unique unless replace_all) and returns a unified diff. Indentation the model got wrong is forgiven when the passage is otherwise unique, the file's own kept; a passage that is not there is answered with the closest one, numbered.	Working dir
file_write	Writes a whole file, creating parent directories as needed.	Working dir
file_list	Lists files and directories under a path.	Working dir
glob	Finds files by name pattern, newest first.	Working dir
grep	Searches file contents for a regular expression under a directory or in one file, file:line: text, with glob, ignore_case, context, files_only and a result cap; binary files and build directories skipped.	Working dir
fetch_tool_result	Reloads the full content of a tool result evicted from the live context.	—

Orchestration tools (mc-agent-runtime-core)

Tool	Description	Needs
run_agent	Delegates a task to another agent by name — see sub-agents. Added by the runtime when the agent's roster names someone.	—
run_agents	Fans several sub-agent calls out in parallel. Added with run_agent.	—
tool_search	Lets the agent find and activate its deferred tools on demand. Added by the runtime when a tool is deferred.	—
skill	Loads the full instructions of one skill; the prompt carries only names and descriptions. Injected, not assigned.	The agent's skills config
view_attachment	Shows an attached image or PDF to the model again — as a message of its own in the running turn, since media goes with a message in its own turn only. Activated for a session when an image or PDF is attached; see images and documents as message parts.	—

The file tools resolve paths against the session's working directory — the directory the user is in. The CLI sets it to the directory it was launched in and changes it with /cd; the chat has a folder button on its composer that names the directory and opens a chooser; the REST API takes workingDir on POST /api/sessions and PUT /api/sessions/{id}/working-dir. The model is told where it is in the system prompt, bash runs there, glob searches it from ., and a sub-agent called from the session inherits it.

A session can reach additional directories beside its working directory — a library checked out next to the project, a data folder — by absolute path (/add-dir in the CLI, Additional directories in the chat's chooser, additionalDirs on the API). Relative paths always mean the working directory; anything outside the working directory and the additional ones is refused with an error naming the allowed directories.

The chat's chooser works like the operating system's folder dialog: one path field, the folders inside it to step into (and Up), and Use this folder takes what the field says — typed or clicked, empty for the server's default. It browses the server's tree under mindconnect.tools.working-dir-root and nothing beyond it. The additional directories are listed under the folders with a Remove each, and Add this folder adds the field's path as one more. New folder creates a directory inside the one shown and steps into it. On a multi-user server give the root a {user} placeholder (/srv/mindconnect/users/{user}): each user then picks from, and works in, a tree of their own.

Every session has a directory of its own. A session opened without a working directory works in it: sessions/<session-id> under the user's home (mindconnect.users.home, by default <data.base-dir>/<namespace>/home/{user}). The files attached to a chat are put in its uploads/ for the file tools — the system prompt names each file's path — and when the user moves the session to a project, the session's own directory stays reachable as an additional directory. On a server a working directory must lie under mindconnect.tools.working-dir-root, by default the user's home; the CLI sets that root to / and works where it was launched.

A session with no directory at all — one written before 0.5.2, a runtime without a users' home — falls back to the tool's own baseDir override, then the base directory (mindconnect.tools.base-dir), which defaults to the user home of the process.

Web tools (mc-agent-tools-web)

Tool	Description	Needs
web_search	Searches the web — the agent's first stop for web information.	TAVILY_API_KEY — the tool is disabled if it's not set
web_read	Fetches and reads the full content of a specific URL as text (HTML converted to text).	—

web_search uses Tavily. Provide the key via the TAVILY_API_KEY environment variable; without it the factory reports the tool as unavailable.

Browser tool (mc-agent-tools-web-browser)

Tool	Description	Needs
web_read_browser	Fetches a URL via a headless browser (JavaScript executed) and returns the rendered page — for JS-heavy sites web_read can't handle.	Playwright Chromium (downloaded on first use)

Document tools (mc-agent-tools-document)

For long PDFs and Word .docx files. No keys required (base dir config like the file tools).

Tool	Description
document_outline	Returns the structural outline of a long document (PDF / .docx).
document_sections	Lists a document's sections.
read_document	Reads a specific page range from a long document.
read_document_section	Reads one section by reference.
grep_document	Searches inside a single long document for a regex pattern.
document_file_read	Reads a document file from the base directory.
document_write	Writes a document file.

Code execution (mc-agent-tools-code)

Tool	Description	Needs
code_execute	Runs code in a disposable container sandbox (docker/podman). The chat's working and additional directories are mounted writable under their own host paths (the working one also as /workspace), so files it writes are where bash, the file tools and the chat's Files dialog find them; a session without a working directory gets a scratch directory. Python runs in ghcr.io/mindconnect-ai/code-exec-python, which carries python-pptx, python-docx, openpyxl, matplotlib, pandas and the mc_office generators the office skills call.	A container runtime; limits via mindconnect.code-exec.* (runtime, network, languages, memory, cpus, timeout-seconds, idle-seconds)

Knowledge tools (mc-vector-store-tools)

Semantic search over vector stores; embedding happens inside the tool. Needs an EMBEDDING-type LLM config (default name embeddings, via mindconnect.vector-store.embedding-config). See vector store & file store for the whole knowledge layer.

Tool	Description
vector_upsert	Embeds a file's or document's chunks and lists it in a store (a stored file is embedded once, whatever stores list it; once indexed, it is only listed, never replaced).
vector_search	Semantic similarity search over a store's entries — optionally among some entities (files, documents, mail, …), where metadata has given values.
vector_ingest_file	Chunks and ingests a whole file.
vector_delete_file	Takes a file or document off a store.

Workflow tools (mc-agent-tools-workflow)

Every persisted workflow is exposed as its own tool, workflow_<id>, with parameters generated from the workflow's input schema — the bridge between the agents and the workflow engine.

Todo tools (mc-agent-runtime-core)

A session-scoped planning list the LLM maintains while it works. No keys required.

Tool	Description
todo_write	Creates / updates the session todo list.
todo_read	Reads the current session todo list.

Calendar tools (mc-agent-tools-calendar)

One set of tools for every calendar account the user attached under Connections, whatever kind it is — CalDAV with mc-calendar-caldav on the classpath, and whatever else a distribution plugs in through the CalendarProvider SPI. A call names its account as provider.key (caldav.web), or all where a listing spans them. The three tools that change something are tools of their own, so an agent's binding can make each ask for approval.

Tool	Description
calendar_calendars	Lists the calendars of an account (or all accounts) with their ids, the main one and which are read-only.
calendar_events	Lists appointments in a time window, earliest first — with their reminders where the calendar reports them.
calendar_read	Reads one appointment in full: time, place, organiser, attendees, reminders and notes.
calendar_create	Puts an appointment into a calendar; reminders sets its alarms.
calendar_update	Changes an appointment; what is not given stays as it is, reminders replaces its alarms.
calendar_delete	Deletes an appointment; for a meeting the user organised, the attendees are told.

Reminders

calendar_create and calendar_update take reminders: minutes before the start, as a list of whole numbers — [10] for "remind me 10 minutes before", [60] for "an alarm an hour before", [10, 60] for both. For an all-day entry the minutes count from its first midnight.

reminders	calendar_create	calendar_update
left out	the calendar's default reminder	the reminders stay as they are
[]	no reminder at all	every reminder is removed
[10, 60]	these two	these two, replacing the old ones

What a calendar can keep differs, and the tool result says what became of the reminders asked for rather than claiming more than was set. Each store states its limits as CalendarStore.reminders() (ReminderSupport), and the tools ask it before anything is written:

ReminderSupport	Meant for	More than it keeps
ANY	CalDAV: any number, each a VALARM (ACTION:DISPLAY, TRIGGER:-PT<n>M), no limit ahead	—
upTo(max, maxMinutes)	a calendar with limits, e.g. Google Calendar's 5 per entry and 40,320 minutes (4 weeks)	refused with the limit; nothing is written
onlyOne(maxMinutes)	a calendar with one reminder per entry, e.g. Outlook	the one closest to the start is kept; the result names the ones dropped
NONE (the default)	a store that writes no reminders	the entry is created without them; the result says no reminder was set

A CalDAV update that names reminders replaces every alarm of the appointment (of a recurring one, the series' own; a changed occurrence keeps its alarms). Reading lists an alarm as a reminder when its trigger is a duration before the start; alarms at a fixed moment or relative to the end are kept on the server but not listed. A store that a distribution adds for another kind of account takes no reminders until it overrides reminders().

MCP servers (agents/mcp)

Tools from Model Context Protocol servers are registered, not compiled in. Open MCP Servers in the admin UI, register a server, and its tools join the catalog as <prefix>_<tool> — a server registered with prefix gmail turns its search_emails into gmail_search_emails.

Target	Runs the server as
docker	a container image, talking over stdio
process	a local command such as npx -y …, talking over stdio
http	a remote endpoint over streamable HTTP — https unless it is on localhost

• Try before you save. Test connection starts the server once and lists its tools.
• Suggestions. With MC_MCP_CATALOG_ENABLED=true the screen searches Docker's MCP catalog and prefills a registration; required secrets arrive as ${NAME} placeholders to replace with the value.
• Values are used as entered. A value in env or headers — an API key, say — is stored in the registration and sent as it is. ${NAME} is reserved for variables of the signed-in user; until users can set them, a registration that uses one does not start. The environment of the server process is never read.
• Starting a server here is the installation's decision. process and docker targets run with the rights of the admin UI, and registering asks for a login, not an admin role. They start only where mindconnect.mcp.allow-process / mindconnect.mcp.allow-docker allow it; unset, both follow sign-in — on while mindconnect.auth.enabled is false, off once it is true. http needs neither. A started server inherits only PATH, HOME, locale, proxy and container-daemon variables; anything else it needs goes into its registration's env.
• The prefix is fixed once a server is registered: agents bind the tool names it produces. Register a new server to use a different one.
• Storage: one JSON file per server under <data.base-dir>/<namespace>/system/mcp-servers/, the discovered tools cached beside it. With mindconnect.persistence=postgres the same documents are rows of mc_mcp_server and mc_mcp_schema_cache, per namespace; a namespace's files are imported once, the first time it is used, and left where they are.

Gmail ships as a bundled, disabled registration running @gongrzhe/server-gmail-autoauth-mcp via npx. Run npx @gongrzhe/server-gmail-autoauth-mcp auth once, then enable it in the admin UI.

Assigning tools to an agent

Which tools an agent can use is part of its definition — manage them in the Admin UI → Tools and per-agent in the agent detail view. To add a tool of your own, see creating a tool.