Tool System & Discoverability
JAATO provides tools to AI models through a deferred loading architecture. Rather than loading all 100+ tools upfront, JAATO exposes only a small set of core tools initially. The model discovers additional tools on-demand through introspection, reducing initial context overhead by 70–85%.
Discoverability Modes
Every tool in JAATO has a discoverability attribute that controls when it appears in the model's context:
| Mode | Behavior | When to Use |
|---|---|---|
core | Always loaded in initial context | Essential tools the model needs immediately |
discoverable | Loaded on-demand via introspection | Specialized tools for specific use cases |
All tools default to "discoverable" unless explicitly marked as "core". This means the traditional approach of loading all tool schemas upfront (8,000–15,000 tokens) is replaced by an initial load of ~1,500–2,500 tokens for core tools only.
Core Tool Registry
Core tools represent the minimum viable toolkit for agentic operation, consuming approximately 1,200 tokens:
| Plugin | Tool | Why Core? |
|---|---|---|
introspection | list_tools, get_tool_schemas | Gateway to all other tools — discovery mechanism |
file_edit | readFile | Essential for code understanding (most frequent operation) |
cli | run | Fundamental system interaction (builds, tests, etc.) |
environment | get_environment | Context awareness (OS, working directory) |
todo | 8+ tools | Task management for complex multi-step operations |
Introspection Mechanism
The introspection system bridges core and discoverable tools through a two-step workflow:
list_tools(category="search")— Returns available tools in a category with names and descriptionsget_tool_schemas(names=["web_search"])— Retrieves detailed parameter schemas and activates the tool for use
The activation step is critical: calling get_tool_schemas() automatically adds the requested tools to the provider's declared tool list, making them callable. Before this call, the model cannot invoke discoverable tools.
Available Categories
| Category | Discoverable Tools |
|---|---|
filesystem | updateFile, writeNewFile, removeFile, moveFile, copyFile, glob_files, list_directory, etc. |
search | grep_content, web_search, ast_search |
web | fetch_url, fetch_url_post |
coordination | delegate (subagents), start_background, save_waypoint, etc. |
communication | request_clarification |
memory | list_templates, get_template, create_template, etc. |
MCP | Dynamic tools from connected MCP servers |
Tool Execution Pipeline
Once a tool is available (core or activated), execution follows a six-step pipeline:
- Permission check — Gated by the permission plugin (auto-approved, whitelisted, or user prompt)
- Auto-background check — Long-running tools may be automatically backgrounded
- Executor lookup — Maps tool name to its callable via the plugin registry
- Execute — Runs the tool logic, handles streaming if supported
- Result enrichment — Plugins can modify or augment results post-execution
- Return to model — Success/failure result fed back to the model
Parallel Tool Execution
When the model requests multiple independent tools in a single turn, JAATO executes them concurrently using a thread pool (max 8 workers). This is enabled by default via JAATO_PARALLEL_TOOLS=true.
Each tool call receives a unique call_id for correlation. Permission prompts are serialized through a channel lock to ensure the user sees one prompt at a time, even when multiple tools need approval concurrently.
Tool Inventory Summary
| Category | Core Tools | Discoverable Tools | Total |
|---|---|---|---|
| Introspection | 2 | 0 | 2 |
| Filesystem | 1 | 9+ | 10+ |
| System | 1 | 2+ | 3+ |
| Coordination | 8+ | 5+ | 13+ |
| Search | 0 | 3+ | 3+ |
| Web | 0 | 2+ | 2+ |
| MCP | 0 | dynamic | dynamic |
| Total | ~14 | ~85+ | ~100+ |
Plugin Lifecycle
Tools are provided by plugins managed through the PluginRegistry. Each plugin goes through four phases:
- Discovery — Registry scans entry points and
shared/plugins/directory - Exposure — Plugin is initialized, auto-wired (registry, session, workspace), schemas and executors registered
- Operation — Plugin provides schemas, executors, system instructions, and handles tool calls
- Shutdown — Plugin cleanup on unexpose or session end