Extending the toolset

Three different things get confused here. Pick the right one before writing anything.

You want	Use
A capability that does not exist, backed by a command or script	a Forged Tool
Capabilities from an existing external server	an MCP server
Several existing tools run back to back in one turn	run_script
A documented sequence a human or model should follow	a skill, see skill-forge

Finding a tool that already exists

Only part of the registry is listed in your prompt on a given turn. Before concluding a capability is missing:

1. tool_search with a keyword. It searches ALL registered tools and returns name, origin and description.
2. tool_call with tool and args runs any of them, listed this turn or not.

Sensitive tools that require approval cannot be run through tool_call. Call those directly by name; going through tool_call will be refused, and that refusal is the expected behaviour, not a bug to work around.

Chaining tools in one turn

run_script executes a SEQUENCE without asking the model again between steps. It is the cheapest thing in this file: it removes a full round trip per step.

• steps is a list of {tool, args} objects.
• The output of step N is injectable into a later argument as {{N}}, 1-based.

{"steps":[
  {"tool":"web_search","args":{"query":"rust-analyzer release notes"}},
  {"tool":"file_write","args":{"path":"C:\\tmp\\notes.md","content":"{{1}}"}}
]}

Use it whenever the second call's arguments are fully determined by the first result. Do NOT use it when you need to read the intermediate output and decide: a step whose arguments depend on your judgement belongs in a normal turn.

What you create now is callable now, but not listed until later

Read this before you conclude that something you just created does not exist.

The tool list in your prompt, and the native tool set sent to the provider, are both frozen when the mission starts. Freezing them is what keeps the cached prefix stable and the cost down. So a Forged Tool you create mid-mission will NOT appear in your list, no matter how many times you reload.

The registry behind tool_search and tool_call is live. forged_tool_create loads the new Forged Tool into it on the spot, so it is reachable through tool_call in the same mission, on the next turn.

	This mission	Next mission
A Forged Tool, after forged_tool_create	callable via tool_call, absent from your list	listed normally
A skill, after skill_create	openable via skill_view by name	listed in the catalog

So: do not verify a new Forged Tool by looking for it in your tool list. Verify it by calling it. tool_search on its name, then tool_call with real arguments. Absence from the list proves nothing and is expected.

Creating a Forged Tool

A Forged Tool is a folder. forged_tool_create writes forged_tools/<name>/tool.json, and the script it runs sits beside it in the same folder:

forged_tools/
  meteo/
    tool.json     the manifest: name, description, schema, command
    run.py          the body the command runs

Manifest and body travel together, so forged_tool_delete removes both at once. Never put a Forged Tool script anywhere else.

The layout inside the folder is flat: a Forged Tool is a manifest and the thing it runs, so there is no scripts/ level to create, unlike a skill which also carries references and templates. A Forged Tool that genuinely grows several files may organise them in subfolders of its own, {{forged_tool_dir}}/lib/parse.py and so on, and nothing has to be declared for that to work. Do not add the level for a single file.

forged_tool_create requires name, description and command.

• command is a shell template with {{slots}}, for example python "{{forged_tool_dir}}/run.py" {{ville}}.
• {{forged_tool_dir}} is filled in with the Forged Tool folder. Use it for every path inside the Forged Tool, so the command works whatever directory the node was started from.
• schema is a JSON Schema for the arguments. Every slot in the command must appear as a property. A slot with no matching property is never filled and the command runs malformed. {{forged_tool_dir}} is the exception: it is provided, never declared.
• script_path plus script_content writes the backing script at the same time. script_path is a bare file name such as run.py, not a path: it always lands in the Forged Tool folder.

Procedure:

1. forged_tool_list first, and tool_search on the same keyword. Do not create a duplicate of something already registered.
2. forged_tool_create with all four parts. It loads the Forged Tool into the live registry itself, so there is no reload step to run afterwards.
3. tool_search on the new name to confirm it entered the registry, then tool_call it once with a real argument to confirm it actually runs. Do NOT look for it in your tool list: it will not be there until the next mission, and that is normal.

forged_tool_delete with name removes one, and reloads what remains by itself.

reload_forged_tools rescans the whole forged_tools/ directory. You do not need it after forged_tool_create or forged_tool_delete, which reload by themselves. You DO need it whenever a manifest reached the disk another way: the user edited forged_tools/<name>/tool.json in an editor, a file was copied in, a script generated one. Until it runs, the folder and the registry disagree, and the registry is what gets called. It returns how many tools are loaded, which is how you confirm the new one arrived rather than assuming it did.

Connecting an MCP server

1. mcp_list to see what is already connected.
2. mcp_add with name and command, plus args if the server needs them.
3. reload_mcp. This is not optional. mcp_add only WRITES the server to mcp_servers.json; it does not connect to it, and none of its tools exist until this runs. It returns how many tools became available, so a return of zero is the signal that the server started and exposed nothing, or did not start at all.
4. mcp_list again to confirm it is up. A server that fails to start still appears in configuration, so verify rather than assume.
5. list_mcp_resources shows what it exposes: URI, name, MIME type, description.
6. read_mcp_resource with server_name and uri reads one. The URI must come from list_mcp_resources; do not guess URIs.

mcp_remove with name disconnects one. Run reload_mcp after it too: removal is also a config write, and the connection outlives it until the reload.

Traps

• Looking for the new Forged Tool in your tool list. It is not there and will not be until the next mission. Confirm it with tool_search, not with your eyes.
• A {{slot}} with no schema property. The command runs with the placeholder left in it and fails in a way that looks like a script bug.
• Guessing an MCP URI. They are opaque and server-specific. Always list first.
• Reaching for a Forged Tool when a skill was needed. If the capability already exists and what is missing is knowing HOW to use it, write a skill. A Forged Tool wrapping tools you already have adds a moving part and no capability.
• Relative paths in command. They resolve against the server's working directory, not the user's folder. Use {{forged_tool_dir}} for anything inside the Forged Tool.
• A JSON dropped loose at the root of forged_tools/. It is not loaded. The node logs the folder it should have gone into, and the tool simply never exists.

Failure modes

The Forged Tool was created but does not appear in my tool list. Expected. The list is frozen for the mission. Confirm with tool_search and use it through tool_call. Do not create it a second time.

The Forged Tool was created but tool_call says unknown tool. That one is real. The manifest did not load: a JSON dropped loose at the root of forged_tools/ instead of inside forged_tools/<name>/, or a malformed manifest. Check the node log, fix the folder, and create it again.

The Forged Tool runs but receives empty arguments. Slot names in command and property names in schema disagree. They must match character for character.

run_script step 2 receives the literal text {{1}}. The placeholder is inside a nested structure the substitution does not reach, or the index is wrong: it is 1-based, so the first step is {{1}}, not {{0}}.

An MCP server appears in mcp_list but exposes no resources. It failed to start. Check the command actually runs in a shell first with shell_exec, then re-add it.