Skip to content

Tools ​

Tools are what an agent can do besides writing text: search its memory, read a file, run a command, ask another agent. somora keeps all of them in one catalog, and every agent gets the same tools whichever model or engine it runs on.

What you get ​

  • One catalog for every engine. A tool works the same on claude-cli, grok-cli, codex-cli and openai-compatible models.
  • Only tools that can run. A tool whose configuration is missing is not shown to the model at all, so it cannot pick it by mistake.
  • A switch per agent. Hide single tools, whole families or an external server from one agent, in the web client or in agent.yaml.
  • Results that fit. An oversized result is shortened and the full text is kept in a file the agent can page through.
  • Broken calls repaired. A call with unusable arguments is answered with advice the model can act on. It never breaks the turn.

Try it ​

List every tool the server has registered:

bash
curl -H "Authorization: Bearer $(somora key)" http://127.0.0.1:18737/tools | jq '.count, .tools[].name'

Run one without a model in the loop. Replace <name> with an agent:

bash
curl -H "Authorization: Bearer $(somora key)" -X POST http://127.0.0.1:18737/agents/<name>/tools/time_now \
  -H 'content-type: application/json' -d '{}'

To see and change what one agent is offered, open the Abilities window in the web client. Each tool has a switch there.

The tool families ​

Every tool carries a toolset tag. The tag groups tools for the per-agent switch (toolset:<tag>). There are 66 built-in tools, plus whatever your external MCP servers bring.

ToolsetToolsOffered when
memory10always
dream6when the agent dreams (dreams: true)
wiki4when the agent dreams, and only while it holds an open dream_review loop
time1always
web2web_fetch always, web_search with web.brave.apiKey or web.searxng.baseUrl
file6always, except analyze_file (see below)
exec3always
agents14always (ask_user only in a turn someone watches)
skills2always
sentinel1always
projects6projects.enabled: true
image2imageGen.enabled: true and at least one entry in imageGen.models
video3videoGen.enabled: true and at least one entry in videoGen.models
media1image or video generation is set up
browser1browser.enabled: true
decision1decisions.model names an entry in decisions.models
builder3builder agents only
mcpvariesservers listed under mcp.servers

Memory, docs and resources ​

Toolset memory. The docs and resource tools carry the same tag, so toolset:memory covers all ten.

ToolWhat it does
memory_searchSearches the agent's notes, the shared wiki and the vault in one go.
memory_getReturns the full note or page behind a search hit.
memory_listLists notes, or browses a wiki folder.
memory_writeCreates or replaces a note in the agent's inbox.
memory_editChanges an existing note.
memory_deleteRemoves a note.
somora_docs_listLists the pages of this documentation.
somora_docs_readReads one page of this documentation.
resource_listLists the remote SSH targets the agent may use.
resource_testChecks that one SSH target is reachable.

Dreaming and the wiki ​

Toolsets dream and wiki.

ToolWhat it does
dream_listLists findings from REM and Lucid that wait for review.
dream_getShows one finding in full.
dream_applyApproves a finding, for example turns it into a note.
dream_dismissRejects a finding.
dream_runStarts a phase by hand: phase is deep (default), lucid or rem.
dream_reviewOpens or closes a wiki review loop for a Lucid run: action is start or end.
wiki_editChanges the body, related: or sources: of a wiki page.
wiki_createCreates a wiki page in a folder of the wiki.
wiki_deleteDeletes a wiki page.
wiki_moveMoves or renames a page and rewrites every [[link]] to it.

The four wiki_* tools exist only inside a review loop. While an agent holds the loop it gets them, and loses the exec, agents and skills toolsets plus file_write and file_patch until the loop ends. It may make 3 wiki_* calls per turn (wiki.lucid.maxCallsPerTurn), so you are asked between edits.

Time and web ​

Toolsets time and web.

ToolWhat it does
time_nowReturns the current date, time, weekday and timezone.
web_searchSearches the web through Brave or your own SearXNG, see Web search.
web_fetchFetches a web page as Markdown, or as plain text with extract: text. maxChars caps the answer (default 5000, at most 50000); pages over 750 KB are refused. Addresses inside your own network are refused unless listed in web.fetchAllowPrivate.

web_search asks one of two search providers:

  • Brave, with an API key from the Brave Search dashboard (web.brave.apiKey).
  • SearXNG, a search engine you run yourself (web.searxng.baseUrl). somora asks its /search page for JSON, so the instance must allow it: json under search.formats in its settings.yml.

With one provider set up, that one answers. With both, Brave is asked first. web.search.order changes that:

yaml
web:
  brave:
    apiKey: "BSA..."
  searxng:
    baseUrl: http://192.0.2.20:8888
  search:
    order: [searxng, brave]   # SearXNG first, Brave only when it fails

Every search starts with the first provider in the order. The next one is asked only when the one before fails: no answer within 30 seconds, no connection, a server error, a used-up quota (429) or a refused key. A query the provider rejects as malformed is not sent on, because the next provider would get the same query.

SearXNG returning nothing because none of its engines answered counts as a failure. Nothing found with every engine answering is an empty result. List one provider only to have no reserve. A provider in the order that is not set up stops config.yaml from loading.

The result names the provider that answered (provider). When one before it failed, fallbackFrom lists which and why. When every provider fails, the error lists each one's error, the first provider's first. Options a provider cannot apply are listed under ignored: SearXNG has no country. freshness becomes its time range.

A SearXNG instance can use Brave as one of its own engines. Its searches then count against your Brave quota too, and a Brave outage also thins its results. It is a second path to the web, not an independent one.

Files ​

Toolset file. Every tool works on the somora host or, with target, on a configured SSH resource.

ToolWhat it does
file_readReads a file as numbered lines (N: text), 2000 per call, with the offset to continue.
file_writeCreates or replaces a file.
file_patchReplaces old_string in a file. Tolerates whitespace and indentation drift and shows a diff.
file_searchSearches file contents. Takes include globs, context lines and files_only.
file_listLists a folder, recursively with a glob. Honours .gitignore.
analyze_fileHas an image or PDF described by the vision worker, for models that cannot see.

analyze_file is offered only when vision.worker is set and the agent's current model lacks the image capability. A model that can see reads the picture itself with file_read.

For a builder agent, a write or patch result also carries the language server's errors for the file.

Shell and terminals ​

Toolset exec.

ToolWhat it does
execRuns one shell command, waiting for it or in the background, locally or on an SSH resource.
processHandles background jobs: action is list, poll, log, write or kill.
tmuxKeeps terminal sessions open across turns and drives coding agents in them: action is create, start, prompt, new_conversation, send, capture, read, wait_idle, list, explain or kill, against target: local or an SSH resource.

Destructive command patterns are blocked in exec and in Sentinel check scripts. A resource can lift single blocks with allowBlocked, for a machine that belongs to the agent. tmux send is not filtered: it types into a program that is already running, often a prompt for another tool, where the same words are harmless text.

Background jobs are detached: they survive a somora restart and are tracked on disk. poll checks the real process, never a remembered state. When somora runs as a systemd service, each background job, and a tmux server an agent starts, runs in a systemd scope of its own, so a restart or somora update does not end it.

When a command times out ​

A command that waits for its result runs with no input: a prompt, a confirmation or a REPL gets end-of-input at once instead of waiting for the time limit. With pty: true it has a terminal, and a prompt waits.

At the limit (timeout_ms, 60 seconds unless the call sets it) the command and every process it started are stopped. The result has timed_out: true, and the end of stderr says how long the command had printed nothing and that files, ports or processes it started may remain. It also says what to do next: a larger timeout_ms or background: true for slow work, the cause for a hang.

The same command timing out again on target: local in the same session and folder is counted, also with other calls and edits in between. From the second time the result has timeouts_in_session and a hint that starts with "This exact command has now timed out N times in this session". It asks the agent to find what keeps the command from finishing instead of starting it again unchanged. Nothing is refused.

The count lives in ~/.somora/agents/<agent>/exec-timeouts.json and is forgotten after a day. Spaces do not make another command; a changed argument does.

The tmux guide explains how an agent starts and prompts other coding agents, their states, wait_mode and multiline_safe.

Other agents ​

Toolset agents.

ToolWhat it does
spawn_subagentHands a task to a sub-agent in its own sealed session.
spawn_subagentsStarts several sub-agents in one call.
subagent_statusReports where one sub-agent stands.
subagent_resultFetches a sub-agent's result, or waits for it.
subagent_listLists the agent's sub-agent tasks.
subagent_cancelStops a sub-agent and everything it started.
agent_askSends a message into another agent's session and returns its reply, with the model that answered.
agent_ask_resultFetches or waits for the outcome of an earlier agent_ask: done, failed or pending, with the model that answered and, after a fallback, the one asked for. The message is never sent twice.
agent_ask_cancelTakes an own agent_ask back.
session_listLists chat sessions: the agent's own, another agent's with agent, everyone's with "*".
session_modelSwitches the model of an existing session, or clears the override with clear:true.
builder_dispatchHands a build order to a builder agent and returns a call_id.
builder_reviewAccepts or rejects items of a builder's acceptance list, as the agent that gave the order; rejected items go back to the builder.
ask_userAsks you a question with options, shown as a card with a button per option. Once answered, the question, its details and the options stay in the conversation.

A sub-agent session does not get the tools in subagents.tools.deny, by default agent_ask, agent_ask_result, agent_ask_cancel and builder_review: its answer reaches the parent on its own. The agents guide explains the setting.

What an agent should know about waiting:

  • A spawn is a background task. The default is wait:false: the tool returns a task_id and the parent is woken with a [subagent attention] turn when the sub finishes. attention:false switches the wake off. wait:true waits and returns the result inline.
  • A wait that runs out is not a failure. After agentLoop.longTaskMaxTimeoutMs the tool returns state: "pending" with the task_id. The sub keeps running and the wake still comes.
  • agent_ask behaves the same. No answer within timeout_ms returns state: "pending" with a call_id, and the asker is woken when the answer lands. wait: false returns pending at once.
  • Cancelling a question never aborts the target's turn. A queued call is removed. A running one is withdrawn, and steered says whether the stop message reached the turn. For an external agent the task is stopped instead (A2A).
  • Waits cannot deadlock. A call that would close a circle of agents waiting on each other is refused with an explanation.

A finished sub-agent's result carries facts the model cannot make up:

FieldMeaning
outcomecompleted, partial (the engine forced a finish at a limit), degraded (the sub looped or never answered) or failed.
outcome_reasonWhy, in words.
tool_calls, roundsHow much work the sub did.
files_writtenFiles created or edited with file_write or file_patch.
mediaAbsolute paths of every image or video the sub generated.
follow_upsResults of work the sub started and that finished later.

More parameters:

  • Sessions. The target sees [Message from agent <name>, session <slug>]. An agent_ask without session answers into the session that message came from, otherwise into main. An explicit session always wins. create_session: true, optionally with model: "<alias>", creates a missing session on the target and pins the model on it.
  • Pictures. agent_ask and the spawn_* tools take images: ["/absolute/path.png"]. The receiving agent sees them. A target without vision gets the vision worker's description.
  • Limits. One agent runs at most 4 sub-agents at a time, 16 across the instance. Subs started by a sub count against the parent, and the last slot is kept for top-level spawns.
  • External agents. agent_ask and spawn_subagent also reach an external agent that has A2A access. Without session, agent_ask goes to its conversation with the asker, a2a-<asker>. model and maxRounds are refused for it; images go along as files or download links (A2A). A2A explains the rest.
  • Builders. builder_dispatch may omit builder when exactly one builder exists. A project folder another builder is working in is refused. Work in a worktree beside the project needs that folder in write_allow (builder).

Skills, sentinel and projects ​

Toolsets skills, sentinel and projects.

ToolWhat it does
skillLoads the full text of one skill from ~/.somora/skills/<slug>/SKILL.md.
skill_listLists the skills the agent may use, fresh from disk.
sentinelManages triggers that wake an agent on a schedule or when a check script sees something happen: action is create, dry_run, update, list, get, pause, resume, delete, test, history or purge_completed.
entity_listLists the entities a project can belong to.
project_listLists projects, filtered by entity or tag.
project_getShows one project with its paths.
project_createCreates a project.
project_updateChanges a project: paths, tags and other fields.
project_focusPins a project to the current session.

sentinel with list hides one-shot triggers that already fired (and once checks that woke their agent) unless you pass include_completed. purge_completed drops them all.

Images, video and browser ​

Toolsets image, video, media and browser.

ToolWhat it does
image_generateCreates images from a prompt. Returns paths and metadata. return_image: true also shows the image to the agent.
image_modelsLists the configured image models and what each accepts.
video_generateStarts a video render and returns at once. Takes input files by meaning (opening frame, input video, character image, keyframes and more). The agent is woken when it lands.
video_statusReports on video jobs.
video_modelsLists the configured video models and what each accepts.
media_listFinds images and videos generated earlier, newest first, with an optional type filter.
browserDrives a managed Chromium: op is open, snapshot, act, screenshot, tabs, status, request_handoff, close_tab or stop.

image_generate passes the prompt on unchanged. Its specs, such as aspect_ratio, resolution and quality, are checked against what the chosen model accepts. browser with open can emulate a device and a locale per tab.

Both generate tools take reference_images as file paths. For video the order matters: one picture is the opening frame, two are opening and closing frame.

media_list has its own toolset because the gallery is shared: an install with video only still needs to list what it made.

Decisions ​

Toolset decision.

ToolWhat it does
decision_evaluateAsks the configured decision model boolean, choice and score questions about a supplied state, optionally with up to four images (file paths). Returns probabilities, or unavailable with a reason and guidance.

The images field is offered only when the decision model has the image capability. The decision models page has the details.

Builder tools ​

Toolset builder.

ToolWhat it does
todo_writeKeeps the session's task list shown in the task panel.
plan_writeWrites the plan file. It is the one write allowed in the plan phase.
acceptance_writeKeeps the acceptance list: one item per requirement of the order, with status and evidence (Builder).

In the plan phase a builder does not get file_write, file_patch, process, spawn_subagent and subagent_result.

Tools from MCP servers ​

Toolset mcp. Each server under mcp.servers adds its tools as mcp__<server>__<tool>. They are found at runtime and can be hidden per agent like any built-in tool, a whole server with mcp__<server>__*.

Choosing tools per agent ​

The Abilities window in the web client switches tools per agent: an eye on each tool and one on each family. It writes the agent's agent.yaml, and a change applies from the agent's next turn. You can also write the block yourself:

yaml
# ~/.somora/agents/<your-agent>/agent.yaml
tools:
  deny:
    - toolset:exec          # a whole family, tools added later too
    - mcp__acme__*          # everything from one MCP server, ditto
    - web_search            # one tool
  allow:
    - mcp__acme__fetch      # one tool on inside a family that is off
PatternMatches
web_searchthe tool with exactly this name
toolset:execevery tool with this toolset tag
mcp__acme__*every tool whose name starts with the text before *
*every tool

A tool is decided in this order:

  1. A tool named in deny is off.
  2. A tool matched by allow is on.
  3. A tool matched by a family, server or * rule in deny is off.
  4. Anything else: on for a chat agent, the builder's own list for a builder (next section).

No tools: block means no restriction.

The dream tools (toolset dream) and the wiki writing tools (toolset wiki) are the exception: they follow the agent's dreams switch, on when it dreams and off when it does not, whatever the rules say. The Abilities window shows them with a note instead of a working eye. See Who dreams.

The rules hold wherever a tool runs as the agent: in its chat turns on every engine, and on POST /agents/<name>/tools/<tool>, which runs one tool as the agent without a turn. A tool that is off there answers 403 and does not run, so a lock cannot be stepped around through the API.

What the window writes ​

You clickWritten
A family's eye, offone rule for the family: toolset:<tag> or mcp__<server>__*
A family's eye, onthe rule and the family's single entries removed; a tool still off after that goes under allow
One tool offits name under deny
One tool on inside a family that is offits name under allow, as an exception

A family switched off as a whole shows "off incl. future" in its header: a tool that an MCP server or an update adds later stays off. The window stays editable whatever the file holds. Rules it did not write, such as mcp__*, are listed above the switches and still apply. Every save keeps the previous agent.yaml as agent.yaml.bak-<time> next to it; the newest five stay.

An older form of the block holds only an allow list, meaning "only these tools". It keeps that meaning. The first click rewrites it as * under deny plus the same names under allow, which shows the same tools.

Tip

Every offered tool costs context on every turn. Smaller local models use tools better when they are offered fewer of them.

What a builder gets ​

A builder agent (kind: builder) starts from a short list instead of everything:

file_read  file_write  file_patch  file_search  file_list  analyze_file
exec  process  todo_write  ask_user  plan_write  acceptance_write
spawn_subagent  subagent_result  subagent_cancel
agent_ask  agent_ask_result  skill  skill_list
web_fetch  web_search
project_get  project_list  project_create  project_focus
memory_search  memory_get  time_now

Its own tools.allow adds to this list and its tools.deny removes from it. In the Abilities window a builder shows two groups: its own list, and every other tool under "more", off until you switch one on. Tools added later stay off for a builder.

The three builder tools, todo_write, plan_write and acceptance_write, belong to builders only. A chat agent never gets them, whatever its agent.yaml says, and the window does not offer them.

Questions to you ​

ask_user lets an agent ask you a question with two to six options, each with a short explanation. It can allow several answers at once (multiple) and carries a short header for the card. The question appears as a card above the input in the web client and on the phone, and with numbered options in the TUI.

When you are to approve or pick content, such as a text to post or send, drafts or a plan, the agent puts it in full into details. The card shows it above the options, as formatted text that scrolls on its own when long; the TUI prints it before the question. The agent's reply around the card may be out of view where you answer, the card never is.

It is offered only while someone watches, and who that is decides whether the question waits:

TurnThe question
A chat agent's turn you started, typed or spokenDoes not wait. The agent's turn ends; the card stays until you answer, also after a reload or a restart. A click sends the option as your next message; while the agent is still working, the answer goes into its running turn, like a steered message, whatever the agent's steering setting says. Writing anything else in the chat answers it too.
A chat agent working on a task another system sent over A2AWaits, and goes back to that system.
A builder's turn while the session is attended (see Builder agents)Waits in the task panel.
A turn from Sentinel, another agent or a sub-agentNot offered: nobody would answer.

A waiting question waits 10 minutes for a chat agent and 30 for a builder, unless the agent asks for another time. Without an answer the agent decides itself and says what it decided. Like any tool, tools.deny: [ask_user] in agent.yaml keeps an agent from it.

A chat agent is told in its instructions to ask with ask_user whenever it would end a reply with a question that has clear choices. On claude-cli and codex-cli the tool is always in the model's list when it is offered, not behind the tool search.

Codex has a question tool of its own. Its questions arrive as the same card, without waiting; one card can then hold several questions, some answered in your own words. The answer goes out as one message with each question and its answer.

Codex often keeps working after it asks. An answer that comes while it does goes straight into that turn; it does not wait for the turn to end. This holds for a builder too: Codex's question is a card next to the task panel, while the builder's own ask_user still waits.

How a tool reaches the model ​

EngineHow it gets the tools
claude-cli, grok-clithrough a local MCP server that somora starts for each turn
codex-clias Codex dynamic tools. Codex asks somora, and the tool runs in the server
openai-compatibleas function definitions, run inside the server

All paths are filled from the same catalog and pass the same per-agent filter, so the set is identical on every engine. Every engine also reads the same input description of each tool. The claude-cli and grok-cli engines see the names with a prefix, mcp__somora__<tool>.

Always in the list, or found on demand ​

claude-cli and codex-cli keep most tools behind a tool search: the model sees their names only after it searches. openai-compatible names them at the end of the system prompt, without their input (see below). A short list stays in the model's list on every turn, so it never has to search for the tools used most:

exec, process, tmux, file_read, file_write, file_patch, file_list, file_search, web_search, web_fetch, memory_search, memory_get, memory_write, time_now, agent_ask, agent_ask_result, spawn_subagent, subagent_result, somora_docs_read, skill and ask_user.

The list only ever picks from the tools the agent is offered in that turn. A tool switched off for the agent never shows up, and ask_user only in a turn someone watches (a person, or a task sent over A2A). During a dream review the review tools join it: dream_list, dream_get, dream_apply, dream_dismiss, dream_review and wiki_edit. A builder's whole tool set is in the list, because it is small.

grok-cli always finds tools through its own search. The list is toolCatalog in config.yaml, see Per engine and per model.

Found on demand on openai-compatible ​

Sending every tool with its full description on every request costs a lot: an agent with external MCP servers can send 80 tools that way, often more text than the rest of its prompt. So an openai-compatible model gets the list above, plus two tools of somora's own:

ToolWhat it does
tool_searchFinds tools by English keywords (queries), or returns the full description of named ones (names). Each hit gives the name, one line and a short form of its input.
tool_callRuns one of the other tools: {name, arguments}. A wrong field is named, with the closest real ones.

The other tools are named at the end of the system prompt, one line each, external MCP servers in their own group. Over toolCatalog.search.listingMaxChars the lines shrink, then only the names stay. A model may also call such a tool directly by its exact name; somora runs it all the same.

The tool list and the system prompt stay the same in every round of a turn and between turns, so a backend's prompt cache keeps working: a tool found by search is run through tool_call, never added to the list. The chat shows the tool that ran, under its own name, not tool_call. Three identical failing searches or calls end the tool use of the turn with an answer.

Only offered tools are listed, found or run, in either mode: a tool switched off for the agent is refused by name. A builder always gets all of its tools.

Per engine and per model ​

The list above is the same for every engine. toolCatalog in config.yaml changes it for one engine or one model:

yaml
toolCatalog:
  engines:
    codex-cli: { add: [sentinel] }      # always in the list on codex-cli
    claude-cli: { remove: [tmux] }      # on claude-cli only through the search
    openai-compatible: { mode: all }    # every tool with its schema, no catalog
  models:
    small-local: { mode: all }          # this model only; wins over its engine
    big-local: { add: [sentinel] }      # one more tool in this model's list
SettingEffect
add, removeTool names put into the list or taken out of it, for that engine or model. The model's lists apply after the engine's.
modeopenai-compatible only: catalog (the default) or all. A model's mode wins over its engine's.
a model's nameIts alias or <provider>/<modelId>.

To replace the whole list for every engine, set toolCatalog.alwaysVisible. A tool the agent may not use stays out whatever the list says, a builder keeps all its tools, and grok-cli cannot be changed. A change applies from the agent's next turn.

Results, limits and timeouts ​

Size. A result may be up to 100 000 characters of JSON unless the tool sets its own limit. A larger one is replaced by a marker with truncated, original_size_chars, cap_chars, a preview and a hint. The complete result is saved under ~/.somora/agents/<agent>/tool-output/ and the marker names the file in full_output_file, so the agent can read parts of it with file_read.

Time. A tool call may take 30 seconds (agentLoop.toolCallTimeoutMs). Tools that are known to run long set their own limit, or take it from the call: agent_ask and subagent_result wait as long as the caller asked, up to agentLoop.longTaskMaxTimeoutMs. exec takes timeout_ms, up to one hour.

Several calls at once. When a model asks for several tool calls in one reply on openai-compatible, the calls of tools that change nothing run at the same time: reading and listing files, searching memory and the web, fetching a page, reading docs and skills, and looking up projects, sessions, sub-agents and media. At most agentLoop.maxParallelTools run at once.

Every other call runs alone: it waits for the calls before it, and the calls after it wait for it. The results go back in the order the model asked for them, so the model reads exactly what it would read with one call after another. Whether a model may ask for several calls at once is its parallelToolCalls setting (see Models).

Wrong input. Input is checked against the tool's schema, and the error names the field. A nested object sent as a JSON string is read and accepted. An unknown tool name is answered with up to three similar names.

When a call arrives broken ​

A model writes the arguments of a tool call as text. On openai-compatible engines that text can arrive unusable in two ways.

FaultWhat it isWhat somora does
Cut offThe text stops mid-value, usually because the answer ran out of output allowance.Does not retry, because the same request ends the same way. The model is told the call "arrived cut off after N characters" and to send less in one go.
MalformedComplete, but not valid JSON.Sends the same request again without comment, up to twice. After that the model is told what the parser found, and that a tool without required parameters takes {}.

somora tells the two apart by the text itself: a complete JSON value ends on its closing bracket. The provider's stop reason is not used, because routers rewrite it.

The broken text is never sent back to the model. Backends parse the arguments of earlier calls, so one bad call would make every further round of the turn fail. The call keeps its place in the conversation with empty arguments, and the original text stays in the session record.

Settings ​

Settings in config.yaml that decide whether a tool is offered:

SettingTools it enables
web.brave.apiKey or web.searxng.baseUrlweb_search
vision.workeranalyze_file, for models without the image capability
projects.enabledentity_list and the five project_* tools
imageGen.enabled with imageGen.modelsimage_generate, image_models, media_list
videoGen.enabled with videoGen.modelsvideo_generate, video_status, video_models, media_list
browser.enabledbrowser
mcp.serversmcp__<server>__*

Settings that shape how tools run:

SettingDefaultMeaning
agentLoop.toolCallTimeoutMs30000Time limit of one tool call, unless the tool sets its own.
agentLoop.maxParallelTools8Calls of one reply that run at the same time, for tools that change nothing. 1 runs them one after another. openai-compatible only.
agentLoop.parallelToolHintfalseTells a model with parallelToolCalls: true that independent calls can go in one reply. openai-compatible only.
agentLoop.longTaskMaxTimeoutMs1800000Longest wait of the tools that wait for other work.
wiki.lucid.maxCallsPerTurn3wiki_* calls per turn inside a review loop.
toolCatalog.alwaysVisiblethe list aboveTools kept in the model's list on claude-cli, codex-cli and openai-compatible instead of behind the tool search. Takes effect on the next turn.
toolCatalog.enginesnonePer engine, add and remove lists on top of it, for example codex-cli: {add: [sentinel]}.
toolCatalog.modelsnoneThe same per model alias or <provider>/<modelId>, for example more tools for a model that searches poorly.
toolCatalog.engines.openai-compatible.modecatalogall sends every tool with its schema instead of the list above plus tool_search and tool_call. A model's mode under toolCatalog.models wins over its engine's.
toolCatalog.search.listingMaxChars8000Length limit of the list of the other tools at the end of the system prompt.
toolCatalog.search.defaultResults / maxResults5 / 20Hits per tool_search query, and the most a model may ask for.
codexCli.directToolsunsetOld form of the list for codex-cli only. When set it replaces toolCatalog.alwaysVisible there, and the server log says so once.

Per agent, in agent.yaml:

SettingDefaultMeaning
tools.denynonePatterns of tools to hide from this agent.
tools.allownoneExceptions inside a family that deny switches off. Without such a family rule it means only these tools. For a builder it adds to the builder list.
kindchatbuilder starts from the short builder list.

Routes ​

RouteWhat it does
GET /toolsLists every registered tool with name, toolset, description, inputSchema, maxResultSizeChars and hasAvailabilityCheck. Includes tools that are not offered right now.
POST /agents/:agent/tools/:nameRuns one tool as that agent. The body is the tool's input. A tool the agent has turned off answers 403 and does not run. A failed call answers 400.
GET /agents/:agent/toolsLists the tools this agent could use, each with visible, plus the agent's gating.
POST /agents/:agent/tools/toggleOne click in the Abilities window: {names, visible, group?}. The server writes the rules.
PUT /agents/:agent/toolsWrites { deny: [...], allow: [...] } into the agent's agent.yaml.

Troubleshooting ​

web_search answers from the second provider. The result's fallbackFrom says why the first one failed. searxng search 403 means the instance does not allow JSON: add json to search.formats in its settings.yml and restart it. brave search 429 means the month's quota or the rate limit is used up.

The agent says it has no such tool. Check the "Offered when" column above, then the agent's tools: block. GET /agents/<name>/tools lists only tools whose configuration exists, with visible for each.

A tool is in GET /tools but the agent does not get it. That route lists everything registered. What an agent is offered also depends on configuration, its tools: block, and whether it holds a review loop.

"is hidden while you hold the active dream_review loop". The agent is inside a wiki review. It ends the loop with dream_review({action: 'end'}) and gets its tools back.

"is not available in this context". The tool's configuration is missing, or the call came from outside the situation the tool needs.

A command hangs again and again. Each timeout logs exec.timeout; the second and later timeout of the same command in a session log exec.timeout_repeat with count, total_ms and quiet_ms (how long it printed nothing before it was stopped).

Log lines to look for: tool.invoked (with result_truncated when a result was shortened), tool.input_invalid, tool.invoke_failed, tool.available_threw and agents.tool_gating_updated.

Adding a tool from source ​

A tool is one ToolDefinition object in the somora repository, under src/tools/:

FieldMeaning
nameUnique. Also the MCP method and function name.
toolsetThe family tag.
descriptionWhat the model reads. Write it as policy, not only as API text: "use this INSTEAD of running cat via exec".
inputSchemaZod schema, checked at runtime.
jsonSchemaJSON Schema every engine sees. Write fields and descriptions by hand; the registry copies zod's bounds (minimum/maximum, lengths, item counts) in where it leaves them out, and a parity test keeps the two equal.
handler(input, ctx)Does the work. ctx carries agent, session, config, activeModel and getMemoryManager.
available?(ctx)Optional check. When it returns false or throws, the tool is hidden and a call is refused.
maxResultSizeChars?Own size limit for the result.
defaultTimeoutMs?, timeoutFromInput?, maxTimeoutMs?Own time limits.

Register a new bundle with one registerMany() line in registerAllTools(registry) in src/tools/index.ts. The server and the MCP child process both fill their registry from that function, so every engine picks the tool up.

See also ​