From d616565858bd0fbf59d46008f947179ab15d3390 Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Fri, 17 Jul 2026 15:46:51 -0600 Subject: [PATCH] docs: Updated docs for .tool enable in agent contexts --- REPL.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/REPL.md b/REPL.md index a10ed19..4dd7d98 100644 --- a/REPL.md +++ b/REPL.md @@ -300,7 +300,7 @@ Setting `enabled_tools` or `enabled_mcp_servers` via `.set` requires retyping th | `.mcp enable ` | Add a single MCP server to the enabled list and start it | | `.mcp disable ` | Remove a single MCP server from the enabled list and stop it | -These write through the same layer cascade as `.set` (session > role, else the global in-memory config), and the +These write through the same layer cascade as `.set` (session > agent > role, else the global in-memory config), and the confirmation message tells you which layer was written. Tab completion is state-aware: `enable` offers only entries not currently enabled, `disable` offers only the current list. @@ -309,9 +309,15 @@ Notes on edge cases: * Entries enabled indirectly through a `mapping_tools`/`mapping_mcp_servers` alias cannot be disabled individually; disable the alias or set the full list via `.set` instead. * Disabling an MCP server that a loaded [skill](Skills) granted keeps it running until the skill is unloaded. -* `.tool enable/disable` is unavailable in an agent context outside a session, and `.mcp enable/disable` is - unavailable in agent contexts entirely; agent MCP servers are defined by the agent's own config - (`.edit agent-config`). +* In an agent context, `.tool enable/disable` adjusts a runtime-only filter over the agent's tool pool. It is not part + of the agent's configuration file, meaning agents always start with their full pool (own functions plus + `global_tools`) and it can never enable a tool the agent didn't declare; names outside the agent's pool are rejected. + While no filter is set the full pool is active, so enabling is a no-op and the first disable materializes the pool + into a concrete list minus that tool. The filter is in-memory only and resets when the agent is reloaded. Graph + agents are the exception: they define tools per-node via `tools:` in `graph.yaml`, so `.tool` and + `.set enabled_tools` are rejected there. +* `.mcp enable/disable` is unavailable in agent contexts entirely; agent MCP servers are defined by the agent's own + config (`.edit agent-config`). ## `.edit` - Modify configuration files The `.edit` command lets you modify configuration files for the current mode of the REPL. It will open the selected @@ -347,7 +353,7 @@ The `.list` command lists the assets of a given kind, making them discoverable w | `.list rags` | List all RAGs | | `.list macros` | List all macros | | `.list skills` | List skills available in this context, with descriptions and a `(loaded)` marker for active skills | -| `.list tools` | List the tools that can be enabled/disabled via `.tool [enable\|disable] ` (excludes internal `user__`/`todo__`/`agent__`/`mcp_` tools) | +| `.list tools` | List the tools that can be enabled/disabled via `.tool [enable\|disable] ` (excludes internal tools; in an agent context, lists the agent's tool pool) | | `.list mcp-servers` | List the MCP servers that can be enabled/disabled via `.mcp [enable\|disable] ` (configured servers plus mapping aliases) | `.list skills` honors the same visibility and policy filters as the model-facing `skill__list` tool, so it shows exactly what the model can load in the current role/agent/session context. @@ -507,4 +513,4 @@ or anything else you'd normally run in a terminal, without leaving the REPL. - `!cd /tmp` does _not_ persist. Each `!cmd` runs in a fresh child shell, so subsequent `!pwd` will show the REPL's original working directory, not `/tmp`. - The command is _not_ written to your shell's history file (`~/.bash_history`, `~/.zsh_history`). It is, however, saved - in the REPL's reedline history (use up-arrow to recall). + in the REPL's reedline history (use up-arrow to recall). \ No newline at end of file