Tool Catalogs Belong in APX Runtime, Not APC

One easy way to bloat an agent system is to treat the tool catalog like portable project context.

That is the wrong boundary.

APC is the portable context layer. It carries durable project meaning through AGENTS.md, .apc/, skills, MCP hints, and other repo-owned artifacts. APX is the runtime and tooling layer. It decides what to execute, where to store local state, and which tools to expose on each surface.

The tool catalog belongs on the APX side.

That sounds small, but it matters a lot in daily use.

Why this boundary matters

A project contract should travel well. A runtime capability list should adapt to the moment.

Those are different jobs.

If you push a giant tool catalog into APC, every compatible runtime inherits a lot of operational detail that may be local, temporary, or channel-specific. That makes the portable layer noisier than it should be.

APX takes a better approach. In src/core/agent/tools/registry.js, the full tool schema set is commented as roughly 25 KB / ~6.3 K tokens. That is already large enough to dominate a lightweight turn. So APX does not send the whole catalog everywhere.

Instead, it keeps APC stable and lets runtime exposure stay dynamic.

What APX actually does

On lightweight channels, APX starts with a small base set of tools and reveals the rest on demand.

The code calls this BASE_TOOL_NAMES. It includes common things an agent often needs immediately: project and agent inventory, memory reads, session and message search, file reads and writes, basic shell access, tasks, skills, and discover_tools itself.

Everything else stays out of the first prompt.

That matters most on chat-like surfaces such as Telegram, desktop, and other lightweight channels where prompt budget is tighter and the user usually wants one small action, not a full coding cockpit.

Then APX adds a narrow expansion path: discover_tools().

That handler does two useful things:

• with no arguments, it returns a grouped catalog of tools that exist but are not loaded yet
• with category or exact names, it activates those tools for the next model step

So a lightweight agent does not need browser automation, fetch tools, runtime delegation, or voice tools on every turn. It can ask for them only when the task actually requires them.

Why this is better than a giant always-on list

The benefit is not only token savings.

It also improves separation of concerns.

APC says what the project is.
APX says what the runtime can do right now.

Those should not collapse into one file or one prompt blob.

A project may define agents, memory, commands, and MCP hints in a portable way. But whether a Telegram session should receive browser schemas up front is not a repository truth. It is a runtime decision.

APX makes that decision per channel.

In the same registry file, some channels deliberately get the full catalog up front: routine, api, web, code, and web_code. That also makes sense. If the user already chose a richer surface, APX can spend the budget there.

So the system stays practical in both directions:

• portable context stays small and durable in APC
• runtime capability exposure stays adaptive in APX

Practical example

Imagine a Telegram conversation with a project agent.

The user asks for a quick answer about current tasks. The base tool set is enough: list projects, inspect tasks, read memory, maybe search messages.

Later, the user asks the same agent to inspect a live website.

That is when discover_tools({ category: "browser" }) becomes useful. APX activates the browser tool group, merges those schemas into the next model step, and the agent continues with the richer capability set.

The repository did not change. APC did not get polluted. Only the runtime surface changed, which is exactly what should happen.

Bigger lesson

A lot of agent architectures become messy because they confuse durable context with executable capability.

APC and APX work better when those stay separate.

APC should carry the portable contract: agents, rules, memory worth committing, and machine-safe project facts.

APX should handle runtime mechanics: sessions, channels, prompt budget, local state, tool exposure, and dynamic activation.

Tool catalogs are runtime mechanics.

So the clean rule is simple:

Keep project meaning in APC.

Keep channel-specific tool exposure in APX.

When a surface needs more power, load more tools there. Do not turn the portable context layer into a giant runtime manifest.

Comments

[Alex Shev]

Tool catalogs feel runtime-owned to me too. Project context should explain intent and constraints; runtime context should expose the available actions, permissions, schemas, and current execution surface. Mixing those makes agents harder to audit.