Declare tools Only When Narrowing an APX Agent An agent definition should describe a durable role without freezing a temporary snapshot of the runtime around it. That is why APX treats an omitted tools field differently from a declared list. The rule is small: omit tools when the agent should inherit APX's broad project-agent default. Declare a non-empty list only when you intentionally want a narrower allowlist. This distinction connects the two layers. Agent Project Context (APC) is the portable context layer: the repository can carry an agent definition in .apc/agents/<slug>.md. APX is the daily-use runtime and tooling layer: it resolves that portable definition against the callable tools available on the current machine. Omission preserves capability Consider a project agent created without --tools: apx agent add release-notes \ --role Writer \ --prompt-file ./prompts/release-notes.md APX leaves the Tools frontmatter field undeclared. At runtime, that agent receives the broad default tool allowlist: the callable registry minus operations that belong only to the host, such as changing APX's identity, widening the permission mode, adding projects, or importing agents. This default matters because real work crosses boundaries. A writing agent may need to read files today, call an MCP publishing tool tomorrow, and create a follow-up task next week. If creation writes today's catalog into the portable agent file, new runtime capabilities remain unavailable until someone edits the definition. The APC file becomes an accidental lockfile for APX internals. Omission avoids that coupling. The agent keeps its stable role and instructions while APX supplies an appropriate default from the runtime it actually has. Declaration means deliberate narrowing Now consider a reviewer that should only inspect repository content: apx agent add reviewer \ --role Reviewer \ --prompt-file ./prompts/reviewer.md \ --tools read_file,glob APX writes the selected tools into the agent definition. From then on, the list acts as an allowlist, not documentation or a suggestion. The reviewer does not gain run_shell, write_file, or call_mcp merely because those tools exist in the runtime. That makes a declared list useful for agents with a genuinely constrained job: a read-only reviewer a documentation inspector that should not execute commands a specialist that may call one approved MCP path but not general shell tools The tradeoff is maintenance. A narrow list stays narrow when APX adds capabilities. That is the intended result, but only when restriction was the intent. Copying every currently available tool into the file creates maintenance cost without adding a meaningful boundary. Capability is not prompt size A broad allowlist sounds expensive if you imagine every tool schema entering every prompt. APX separates those concerns. The allowlist answers which tools the runtime may permit. Lightweight channels can still start with a small base set and discover additional tools when needed. So narrowing an allowlist is a capability decision, not a prompt-budget optimization. Use it to remove powers, not to make an agent look tidy. A practical review rule When reviewing .apc/agents/*.md, ask why each tools list exists. If the answer names a boundary — "this reviewer must remain read-only" — keep it. If the answer is "these were the tools available when we created the agent", remove the field and let APX resolve the default. Also remember that runtime-specific overrides can be stricter for one execution. APX routines can replace an agent's normal allowance for a particular run, including running with no tools. That operational decision belongs in APX runtime configuration, while the APC agent file keeps the durable project-level intent. Portable definitions work best when they state constraints that should survive across machines. Omitted tools says capability may evolve with the runtime. A declared list says this boundary must not.