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-cliandopenai-compatiblemodels. - 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:
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:
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.
| Toolset | Tools | Offered when |
|---|---|---|
memory | 10 | always |
dream | 6 | when the agent dreams (dreams: true) |
wiki | 4 | when the agent dreams, and only while it holds an open dream_review loop |
time | 1 | always |
web | 2 | web_fetch always, web_search with web.brave.apiKey or web.searxng.baseUrl |
file | 6 | always, except analyze_file (see below) |
exec | 3 | always |
agents | 14 | always (ask_user only in a turn someone watches) |
skills | 2 | always |
sentinel | 1 | always |
projects | 6 | projects.enabled: true |
image | 2 | imageGen.enabled: true and at least one entry in imageGen.models |
video | 3 | videoGen.enabled: true and at least one entry in videoGen.models |
media | 1 | image or video generation is set up |
browser | 1 | browser.enabled: true |
decision | 1 | decisions.model names an entry in decisions.models |
builder | 3 | builder agents only |
mcp | varies | servers 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.
| Tool | What it does |
|---|---|
memory_search | Searches the agent's notes, the shared wiki and the vault in one go. |
memory_get | Returns the full note or page behind a search hit. |
memory_list | Lists notes, or browses a wiki folder. |
memory_write | Creates or replaces a note in the agent's inbox. |
memory_edit | Changes an existing note. |
memory_delete | Removes a note. |
somora_docs_list | Lists the pages of this documentation. |
somora_docs_read | Reads one page of this documentation. |
resource_list | Lists the remote SSH targets the agent may use. |
resource_test | Checks that one SSH target is reachable. |
Dreaming and the wiki
Toolsets dream and wiki.
| Tool | What it does |
|---|---|
dream_list | Lists findings from REM and Lucid that wait for review. |
dream_get | Shows one finding in full. |
dream_apply | Approves a finding, for example turns it into a note. |
dream_dismiss | Rejects a finding. |
dream_run | Starts a phase by hand: phase is deep (default), lucid or rem. |
dream_review | Opens or closes a wiki review loop for a Lucid run: action is start or end. |
wiki_edit | Changes the body, related: or sources: of a wiki page. |
wiki_create | Creates a wiki page in a folder of the wiki. |
wiki_delete | Deletes a wiki page. |
wiki_move | Moves 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.
| Tool | What it does |
|---|---|
time_now | Returns the current date, time, weekday and timezone. |
web_search | Searches the web through Brave or your own SearXNG, see Web search. |
web_fetch | Fetches 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
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/searchpage for JSON, so the instance must allow it:jsonundersearch.formatsin itssettings.yml.
With one provider set up, that one answers. With both, Brave is asked first. web.search.order changes that:
web:
brave:
apiKey: "BSA..."
searxng:
baseUrl: http://192.0.2.20:8888
search:
order: [searxng, brave] # SearXNG first, Brave only when it failsEvery 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.
| Tool | What it does |
|---|---|
file_read | Reads a file as numbered lines (N: text), 2000 per call, with the offset to continue. |
file_write | Creates or replaces a file. |
file_patch | Replaces old_string in a file. Tolerates whitespace and indentation drift and shows a diff. |
file_search | Searches file contents. Takes include globs, context lines and files_only. |
file_list | Lists a folder, recursively with a glob. Honours .gitignore. |
analyze_file | Has 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.
| Tool | What it does |
|---|---|
exec | Runs one shell command, waiting for it or in the background, locally or on an SSH resource. |
process | Handles background jobs: action is list, poll, log, write or kill. |
tmux | Keeps 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.
| Tool | What it does |
|---|---|
spawn_subagent | Hands a task to a sub-agent in its own sealed session. |
spawn_subagents | Starts several sub-agents in one call. |
subagent_status | Reports where one sub-agent stands. |
subagent_result | Fetches a sub-agent's result, or waits for it. |
subagent_list | Lists the agent's sub-agent tasks. |
subagent_cancel | Stops a sub-agent and everything it started. |
agent_ask | Sends a message into another agent's session and returns its reply, with the model that answered. |
agent_ask_result | Fetches 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_cancel | Takes an own agent_ask back. |
session_list | Lists chat sessions: the agent's own, another agent's with agent, everyone's with "*". |
session_model | Switches the model of an existing session, or clears the override with clear:true. |
builder_dispatch | Hands a build order to a builder agent and returns a call_id. |
builder_review | Accepts or rejects items of a builder's acceptance list, as the agent that gave the order; rejected items go back to the builder. |
ask_user | Asks 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 atask_idand the parent is woken with a[subagent attention]turn when the sub finishes.attention:falseswitches the wake off.wait:truewaits and returns the result inline. - A wait that runs out is not a failure. After
agentLoop.longTaskMaxTimeoutMsthe tool returnsstate: "pending"with thetask_id. The sub keeps running and the wake still comes. agent_askbehaves the same. No answer withintimeout_msreturnsstate: "pending"with acall_id, and the asker is woken when the answer lands.wait: falsereturnspendingat once.- Cancelling a question never aborts the target's turn. A queued call is
removed. A running one iswithdrawn, andsteeredsays 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:
| Field | Meaning |
|---|---|
outcome | completed, partial (the engine forced a finish at a limit), degraded (the sub looped or never answered) or failed. |
outcome_reason | Why, in words. |
tool_calls, rounds | How much work the sub did. |
files_written | Files created or edited with file_write or file_patch. |
media | Absolute paths of every image or video the sub generated. |
follow_ups | Results of work the sub started and that finished later. |
More parameters:
- Sessions. The target sees
[Message from agent <name>, session <slug>]. Anagent_askwithoutsessionanswers into the session that message came from, otherwise intomain. An explicitsessionalways wins.create_session: true, optionally withmodel: "<alias>", creates a missing session on the target and pins the model on it. - Pictures.
agent_askand thespawn_*tools takeimages: ["/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_askandspawn_subagentalso reach an external agent that has A2A access. Withoutsession,agent_askgoes to its conversation with the asker,a2a-<asker>.modelandmaxRoundsare refused for it;imagesgo along as files or download links (A2A). A2A explains the rest. - Builders.
builder_dispatchmay omitbuilderwhen exactly one builder exists. A project folder another builder is working in is refused. Work in a worktree beside the project needs that folder inwrite_allow(builder).
Skills, sentinel and projects
Toolsets skills, sentinel and projects.
| Tool | What it does |
|---|---|
skill | Loads the full text of one skill from ~/.somora/skills/<slug>/SKILL.md. |
skill_list | Lists the skills the agent may use, fresh from disk. |
sentinel | Manages 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_list | Lists the entities a project can belong to. |
project_list | Lists projects, filtered by entity or tag. |
project_get | Shows one project with its paths. |
project_create | Creates a project. |
project_update | Changes a project: paths, tags and other fields. |
project_focus | Pins 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.
| Tool | What it does |
|---|---|
image_generate | Creates images from a prompt. Returns paths and metadata. return_image: true also shows the image to the agent. |
image_models | Lists the configured image models and what each accepts. |
video_generate | Starts 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_status | Reports on video jobs. |
video_models | Lists the configured video models and what each accepts. |
media_list | Finds images and videos generated earlier, newest first, with an optional type filter. |
browser | Drives 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.
| Tool | What it does |
|---|---|
decision_evaluate | Asks 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.
| Tool | What it does |
|---|---|
todo_write | Keeps the session's task list shown in the task panel. |
plan_write | Writes the plan file. It is the one write allowed in the plan phase. |
acceptance_write | Keeps 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:
# ~/.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| Pattern | Matches |
|---|---|
web_search | the tool with exactly this name |
toolset:exec | every 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:
- A tool named in
denyis off. - A tool matched by
allowis on. - A tool matched by a family, server or
*rule indenyis off. - 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 click | Written |
|---|---|
| A family's eye, off | one rule for the family: toolset:<tag> or mcp__<server>__* |
| A family's eye, on | the rule and the family's single entries removed; a tool still off after that goes under allow |
| One tool off | its name under deny |
| One tool on inside a family that is off | its 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_nowIts 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:
| Turn | The question |
|---|---|
| A chat agent's turn you started, typed or spoken | Does 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 A2A | Waits, 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-agent | Not 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
| Engine | How it gets the tools |
|---|---|
claude-cli, grok-cli | through a local MCP server that somora starts for each turn |
codex-cli | as Codex dynamic tools. Codex asks somora, and the tool runs in the server |
openai-compatible | as 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:
| Tool | What it does |
|---|---|
tool_search | Finds 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_call | Runs 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:
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| Setting | Effect |
|---|---|
add, remove | Tool names put into the list or taken out of it, for that engine or model. The model's lists apply after the engine's. |
mode | openai-compatible only: catalog (the default) or all. A model's mode wins over its engine's. |
| a model's name | Its 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.
| Fault | What it is | What somora does |
|---|---|---|
| Cut off | The 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. |
| Malformed | Complete, 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:
| Setting | Tools it enables |
|---|---|
web.brave.apiKey or web.searxng.baseUrl | web_search |
vision.worker | analyze_file, for models without the image capability |
projects.enabled | entity_list and the five project_* tools |
imageGen.enabled with imageGen.models | image_generate, image_models, media_list |
videoGen.enabled with videoGen.models | video_generate, video_status, video_models, media_list |
browser.enabled | browser |
mcp.servers | mcp__<server>__* |
Settings that shape how tools run:
| Setting | Default | Meaning |
|---|---|---|
agentLoop.toolCallTimeoutMs | 30000 | Time limit of one tool call, unless the tool sets its own. |
agentLoop.maxParallelTools | 8 | Calls of one reply that run at the same time, for tools that change nothing. 1 runs them one after another. openai-compatible only. |
agentLoop.parallelToolHint | false | Tells a model with parallelToolCalls: true that independent calls can go in one reply. openai-compatible only. |
agentLoop.longTaskMaxTimeoutMs | 1800000 | Longest wait of the tools that wait for other work. |
wiki.lucid.maxCallsPerTurn | 3 | wiki_* calls per turn inside a review loop. |
toolCatalog.alwaysVisible | the list above | Tools 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.engines | none | Per engine, add and remove lists on top of it, for example codex-cli: {add: [sentinel]}. |
toolCatalog.models | none | The same per model alias or <provider>/<modelId>, for example more tools for a model that searches poorly. |
toolCatalog.engines.openai-compatible.mode | catalog | all 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.listingMaxChars | 8000 | Length limit of the list of the other tools at the end of the system prompt. |
toolCatalog.search.defaultResults / maxResults | 5 / 20 | Hits per tool_search query, and the most a model may ask for. |
codexCli.directTools | unset | Old 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:
| Setting | Default | Meaning |
|---|---|---|
tools.deny | none | Patterns of tools to hide from this agent. |
tools.allow | none | Exceptions 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. |
kind | chat | builder starts from the short builder list. |
Routes
| Route | What it does |
|---|---|
GET /tools | Lists every registered tool with name, toolset, description, inputSchema, maxResultSizeChars and hasAvailabilityCheck. Includes tools that are not offered right now. |
POST /agents/:agent/tools/:name | Runs 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/tools | Lists the tools this agent could use, each with visible, plus the agent's gating. |
POST /agents/:agent/tools/toggle | One click in the Abilities window: {names, visible, group?}. The server writes the rules. |
PUT /agents/:agent/tools | Writes { 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/:
| Field | Meaning |
|---|---|
name | Unique. Also the MCP method and function name. |
toolset | The family tag. |
description | What the model reads. Write it as policy, not only as API text: "use this INSTEAD of running cat via exec". |
inputSchema | Zod schema, checked at runtime. |
jsonSchema | JSON 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
- Agents: sub-agents,
agent_askand sessions in detail - Builder agents: mode, phase and the task panel
- Memory: the memory tools and how recall ranks
- Wiki: the shared long-term layer
- Dream phases: REM, Deep, Lucid and the review loop
- File tools: limits of the file tools and
analyze_file - Resources: SSH targets and
allowBlocked - tmux: shell and TUI session patterns
- External MCP servers: connecting tool servers
- Skills: the skill system and per-agent visibility
- Sentinel: scheduled triggers and check triggers
- Projects: project manifests
- Image generation and video generation
- Shared browser: the managed browser and handoffs
- Language servers: the
errorsa builder gets after a write - TUI display:
/showand/verbosefor tool calls - Thinking: thinking depth across engines
- API: all routes