Tool System

Tools are the agent's actions. All tools implement the Tool ABC from navi/tools/base.py.

Two tiers

Built-in tools (navi/tools/)

Registered in build_default_registries() as builtins. Never removed on hot-reload.

User tools (tools/*.py)

Written manually or via create_mcp_server. Auto-discovered at startup.

• Files starting with _ are ignored.
• tools/enabled.json — list of user tool names to include in all profiles automatically.
• tools/_template.py — canonical format reference (not loaded).

Currently present: get_current_datetime.py, gmail.py, weather.py.

Tool formats

Module-level format (preferred for user tools)

name = "my_tool"
description = "What it does and when to use it — be specific."
parameters = {
    "type": "object",
    "properties": {
        "param": {"type": "string", "description": "..."}
    },
    "required": ["param"]
}

async def execute(params: dict) -> str:
    # Return a plain string on success.
    # Raise an exception to signal failure.
    return "result"

No classes, no module-level print(). The loader wraps execute in a Tool subclass automatically.

Class-based format (built-in tools)

from navi.tools.base import Tool, ToolResult

class MyTool(Tool):
    name = "my_tool"
    description = "..."
    parameters = {"type": "object", "properties": {...}, "required": [...]}

    async def execute(self, params: dict) -> ToolResult:
        return ToolResult(success=True, output="result")

ToolResult fields:

• success: bool
• output: str — always a string; LLM sees this
• error: str | None — included in output on failure via to_message_content()
• metadata: dict — internal hints (e.g. is_image: True → triggers image injection into context)

Tool loading (navi/tools/loader.py)

load_tools_from_dir(tools_dir) returns LoadResult(loaded, errors).

Load order:

1. Try module-level format (checks for name, description, parameters, execute).
2. Fall back to class-based (scans for Tool subclasses).

Errors are isolated per file — one broken file does not prevent others from loading. Errors are logged and returned in LoadResult.errors.

Middleware hooks

Tools support before_execute / after_execute middleware hooks registered via ToolRegistry.add_middleware(). The built-in LoggingMiddleware logs every tool call with duration and result summary.

Use middleware for cross-cutting concerns: metrics, rate limiting, authorization, audit logging.

Hot-reload

reload_tools tool calls ToolRegistry.reload_user_tools(tools_dir):

1. Drops all tools that are NOT in _builtin_names.
2. Re-runs load_tools_from_dir.
3. New tools registered without server restart.

New tools become available from the next user message (tool schemas are built at run_stream() entry, not during execution).

Self-extension via MCP servers

New capabilities are added as MCP servers using create_mcp_server. The server scaffolding includes:

1. A directory under mcp-servers/{name}/.
2. A server.py entrypoint with stdio transport.
3. A config file at mcp_servers.d/{name}.json.
4. Registration via reload_tools or server restart.

The agent should call tool_manual("create_mcp_server") before using it for the first time.

Scratchpad and Todo

Both are per-session, backed by the PostgreSQL KV-store (session_store table) and survive server restarts.

Scratchpad — named sections for working notes within a task. Operations: write, append, read, clear. Subagents get isolated scratchpads (unique UUID-based session ID in run_ephemeral()).

Todo — checklist for tracking multi-step plans. Operations: set (replace all tasks), update (set status of one task), read. Statuses: pending, in_progress, done, failed, skipped.

Image tool flow

When image_view succeeds, it returns ToolResult with metadata={"is_image": True, "base64": "..."}.

The agent detects this and appends a synthetic user message with the image to session.context (but not session.messages). This makes the image visible to the next LLM call without polluting the display history.

See sessions.md for the dual-buffer design.