Tool registration is duplicated between _TOOL_DISPATCH and _DIR_TOOLS #56

New issue

Open

opened 2026-04-07 05:26:13 +00:00 by archeious · 0 comments

archeious commented

2026-04-07 05:26:13 +00:00

Owner

Adding a new tool the dir agent can call requires updating two places in ai.py:

_TOOL_DISPATCH at ai.py:645 — name → handler function
_DIR_TOOLS at ai.py:151 — Anthropic-shaped tool schema (name, description, input_schema)

Forgetting one half is silent: the agent will either see a tool it cannot dispatch (KeyError on call) or have a dispatchable tool it never knows about. Internals.md §9.1 documents this as a 5-step process per tool, which is friction.

Fix

Small registration helper, e.g.:

@dir_tool(
    name="read_file",
    description="...",
    schema={"type": "object", "properties": {...}, "required": [...]},
)
def _tool_read_file(args, target, cache):
    ...

The decorator appends to a single registry that exposes both the dispatch dict and the schema list.

Notes

Discovered during Session 5 documentation deep dive (#53)
Phase 3.5 (MCP backend, #39) will replace _TOOL_DISPATCH with dynamic discovery from an MCP server. That makes this issue partially moot — the duplication problem evaporates once tools come from the server. Two options:
- Defer until after #39 — accept the duplication for now, let it die with the Python dispatch table
- Fix now — easier to migrate one well-structured registry to MCP than to migrate two parallel structures
Not blocking Phase 3, but worth deciding on before Phase 3.5

Adding a new tool the dir agent can call requires updating two places in `ai.py`: 1. `_TOOL_DISPATCH` at `ai.py:645` — name → handler function 2. `_DIR_TOOLS` at `ai.py:151` — Anthropic-shaped tool schema (name, description, input_schema) Forgetting one half is silent: the agent will either see a tool it cannot dispatch (KeyError on call) or have a dispatchable tool it never knows about. Internals.md §9.1 documents this as a 5-step process per tool, which is friction. ## Fix Small registration helper, e.g.: ```python @dir_tool( name="read_file", description="...", schema={"type": "object", "properties": {...}, "required": [...]}, ) def _tool_read_file(args, target, cache): ... ``` The decorator appends to a single registry that exposes both the dispatch dict and the schema list. ## Notes - Discovered during Session 5 documentation deep dive (#53) - **Phase 3.5 (MCP backend, #39) will replace `_TOOL_DISPATCH` with dynamic discovery from an MCP server.** That makes this issue partially moot — the duplication problem evaporates once tools come from the server. Two options: - **Defer until after #39** — accept the duplication for now, let it die with the Python dispatch table - **Fix now** — easier to migrate one well-structured registry to MCP than to migrate two parallel structures - Not blocking Phase 3, but worth deciding on before Phase 3.5