# Plan: `/tools` REPL Command

List all available tools (built-in, MCP, A2A) in the current session.

## What it does

A new `/tools` REPL command that prints every tool the agent can call, grouped
by source, with full descriptions:

```
Built-in tools:
  read_file        Read the contents of a file or list a directory. For files, ...
  write_file       Create or overwrite a file.
  use_skill        Activate a skill to get detailed instructions. Available skills: fix, explain.
  run_command      Run a command and return its output. Allowed commands: make, pytest.
  ...

MCP tools (2 servers):
  filesystem:
    mcp__filesystem__read       Read a file from the filesystem.
  github:
    mcp__github__create_issue   Create an issue.
    mcp__github__search_repos   Search GitHub repositories.

A2A tools (1 agent):
  coder:
    a2a__coder__code_review     Review code for quality issues.
                                Examples: review this PR; check for security issues
```

If no MCP/A2A tools are present, those sections are omitted.

## Design decisions

**Full descriptions, not truncated.** Tools like `use_skill` and `run_command`
have session-specific details appended after the first sentence (available skill
names, whitelisted commands). Truncating to the first sentence would hide the
information the user actually needs. Show the complete `function.description`.

**Newline handling in descriptions.** Some descriptions contain embedded
newlines (e.g. A2A skill descriptions with `\nExamples: ...` from
`a2a_client.py:455`). Normalize these to a hanging-indent format: the first
line follows the tool name at its normal column, and continuation lines are
indented to the same column. This keeps the aligned layout intact without
losing the multi-line content.

**Server/agent counts from the managers, not the tools list.** Both
`McpManager.get_tool_info()` and `A2aManager.get_tool_info()` return
`{server_name: [(namespaced_name, description), ...]}`. Use these for the
MCP/A2A sections — they give authoritative server/agent grouping and counts
without parsing prefixes. The managers are already passed to `repl_loop`.
For built-in tools, classify as "everything not in the MCP/A2A tool info".

**Fully sorted output.** Tools sorted alphabetically within each group.
Server/agent subgroup names are also sorted alphabetically. Sections
themselves follow a fixed order: built-in, MCP, A2A. Makes output stable and
tests straightforward.

## Implementation

### 1. Add `_repl_tools()` helper in `agent.py` (~3690 area)

```python
def _repl_tools(tools: list, mcp_manager=None, a2a_manager=None) -> None:
```

- Collect MCP/A2A namespaced names from managers (if present) via
  `get_tool_info()`. This gives `{server: [(name, desc), ...]}`.
- Everything else in `tools` is built-in: extract `function.name` and
  `function.description`, sort alphabetically.
- For each tool, replace embedded newlines in the description with
  `\n` + padding to the description column, producing a hanging indent.
- Build a multi-line string with sections and print via `fmt.info()`.
- MCP/A2A sections show sub-groups by server/agent name (sorted
  alphabetically) with the count in the header derived from the dict keys.

### 2. Wire it into the REPL command dispatch (~line 4010)

Add an `elif cmd == "/tools":` branch that calls
`_repl_tools(tools, mcp_manager, a2a_manager)` and continues.

### 3. Add `/tools` to the `/help` text (~line 3696)

One new line:
```
  /tools             List all available tools
```

### 4. Update `docs.md/usage.md`

Add a `/tools` entry in the REPL Commands section (~line 48), following the
style of existing entries:

```
`/tools` lists all tools available in the current session — built-in, MCP, and
A2A — grouped by source with full descriptions.
```

Then rebuild the site with `make website`.

### 5. Tests in `tests/test_repl.py`

**Integration test** — follow the pattern of `test_help_in_repl` (line 423):
mock `PromptSession` to feed `/tools` then `/exit`, patch `run_agent_loop`,
and assert:

- `run_agent_loop` is never called (the command is handled locally).
- `messages` list is not mutated (still only the initial system message).
- The tool names from the `tools` list appear in captured stderr output.

**Unit test for `_repl_tools()`:**

- Build a `tools` list with built-in, `mcp__`, and `a2a__` entries.
- Pass mock managers whose `get_tool_info()` returns known dicts.
- Capture stderr, assert correct grouping, alphabetical order within
  groups, alphabetical order of server/agent subgroup names, full
  descriptions present (including multi-line with hanging indent),
  and correct server/agent counts in headers.
- A second case with no managers: assert MCP/A2A sections are absent.

**Embedded newline test:**

- Build a tool with `\n` in the description (mimicking A2A examples).
- Assert the output renders continuation lines at the hanging indent
  column, not as raw newlines breaking alignment.

**Help text assertion:**

- Extend the existing `test_help_prints_commands` (line 411) with
  `assert "/tools" in captured.err` to verify `/tools` appears in `/help`
  output.

## Files changed

- `swival/agent.py` — helper + REPL dispatch + help text
- `docs.md/usage.md` — new `/tools` entry
- `docs/pages/usage.html` — rebuilt via `make website`
- `tests/test_repl.py` — integration + unit + help-text tests
