Facio's Tool Architecture: How a Composable Runtime Turns LLM Calls Into Real-World Actions
An LLM that can only generate text is a research tool, not a worker. The real power of AI agents comes from tools — the structured interface that turns model reasoning into real-world actions. A file write. A database query. A shell command. A browser click. A payment. A deployment. Each tool extends the agent's reach one step further from "answer a question" to "change the world."
Facio's tool architecture is built for composability. Every tool follows the same patterns. Every tool respects the same HITL boundaries. And every tool can be combined with every other tool to build workflows that no single tool enables. Here's how the architecture works.
The Three Layers of Agent Capability
Facio's runtime organizes tools into three functional layers:
Perception tools — the agent learns about the world. read_file, web_search, web_fetch, read_logs, browser_snapshot, glob, grep. These tools gather information; they don't change anything.
Action tools — the agent changes the world. write_file, edit_file, exec, generate_image, generate_video, notebook_edit, message, browser_click. These tools produce side effects; they leave the system in a different state.
Coordination tools — the agent manages its own operation. cron, heartbeat, spawn, switch_model, manage_mcp, manage_channel, manage_credentials. These tools configure and orchestrate; they shape how the agent uses the other tools.
Every Facio tool fits into exactly one of these layers. The classification isn't decorative — it informs the safety model, the audit trail structure, and the HITL gating pattern for each tool.
The Universal Tool Contract
Despite serving different purposes, every Facio tool follows the same underlying contract:
| Property | How it works |
|---|---|
| Structured schema | Each tool has typed parameters, validated at call time |
| Standardized error format | Errors return structured responses the agent can reason about |
| Audit trail integration | Every invocation is logged with timestamp, caller, and result |
| HITL-aware defaults | Destructive operations require explicit approval; non-destructive run immediately |
| Workspace awareness | File-related tools respect WORKSPACE.md layout conventions |
| Credential isolation | Secret-bearing tools integrate with ${credentials.KEY} placeholders |
This uniformity is what makes the architecture composable. The agent doesn't need special-cased logic for each tool — it uses the same patterns everywhere. The HITL gating for manage_mcp works the same way as the HITL gating for manage_credentials. The audit trail format for exec matches the format for read_logs. The error handling for web_fetch matches notebook_edit.
When the agent learns how to use one Facio tool well, it understands the pattern. When it needs a new tool, the pattern transfers.
The Safety Hierarchy
Tools don't have uniform risk profiles. read_file is essentially safe — reading a file can leak information but can't destroy data. exec is high-risk — a shell command can do anything the agent's user can do. The architecture reflects this:
| Risk tier | Tools | HITL gating |
|---|---|---|
| Tier 0: Read-only | read_file, grep, glob, web_search, web_fetch, read_logs | None — read operations can't destroy data |
| Tier 1: Local modifications | write_file, edit_file, notebook_edit, patch_file | None for workspace files; flagged for files outside workspace |
| Tier 2: System effects | exec, generate_image, generate_video, message | None by default; agent should request approval for high-impact actions |
| Tier 3: Infrastructure | manage_mcp, manage_channel, manage_credentials, cron | Destructive operations (add, remove, edit) require approval |
| Tier 4: Identity changes | switch_model, spawn (recursive) | Require explicit approval for every invocation |
The agent doesn't have to know this taxonomy — it's enforced in the runtime. But understanding it explains why some tools feel "instant" and others feel "gated." The gating matches the risk, not the convenience of the implementation.
The Composition Patterns
Composability is the real test of a tool architecture. A tool set that handles 30 separate use cases poorly is less valuable than a tool set that handles 5 patterns but composes them into 100 workflows. Facio's tools compose in three primary ways:
Composition Pattern 1: Pipeline
The output of one tool feeds the input of the next:
web_search(query="...")
→ identifies URLs
→ web_fetch(url=URL)
→ extracts content
→ grep(pattern="...", path="downloads/")
→ finds references
→ read_file(path="...")
→ reads specific section
Each tool does one thing well. The agent chains them. The pipeline reads naturally as a sequence of operations — exactly how a human researcher would approach the same task.
Composition Pattern 2: Branching
Tools make decisions based on the output of earlier tools:
read_logs(level="ERROR", since="1h")
→ detects failure
→ branch on error type:
- "MCP server down" → manage_mcp(action="restart", name=server)
- "Rate limit" → switch_model(model="gpt-4o-mini")
- "Permission denied" → ask_approval(title="Permission required")
The agent reads the error, classifies it, and routes to the right recovery tool. The decision logic is in the agent's reasoning; the tools just provide the actions.
Composition Pattern 3: Parallelism with Spawn
Independent work runs concurrently:
spawn(task="Research X", model="claude-sonnet-4-7")
spawn(task="Research Y", model="gpt-4o")
spawn(task="Research Z", model="gemini-2.5-pro")
→ three sub-agents run in parallel
→ each uses different tools
→ parent agent waits for results
→ synthesizes into final deliverable
spawn is the composition primitive for parallel work. The sub-agents have their own tool surface, their own context, their own audit trail — but they execute concurrently, multiplying the agent's effective throughput.
The Tool Discovery Model
When the agent starts a session, it sees the full tool surface in its context. The model is given tool names, parameter schemas, and usage examples for every available tool. The agent doesn't need to "look up" tools — they are part of its instruction.
For skills, the model uses a different discovery mechanism:
# Skill discovery: agent reads SKILL.md from the skills directory
read_file(path="skills/html-slides/SKILL.md")
→ sees the skill description
→ sees the available scripts
→ sees the linked templates
→ uses the skill
Skills extend the agent's capability through a documentation convention, not through the core tool surface. Built-in tools are part of the model's instruction; skills are discovered at runtime. Both follow the same composition patterns.
The Integration Layer: MCP
What happens when a tool Facio doesn't have is needed? The Model Context Protocol (MCP) extends the tool surface dynamically:
manage_mcp(action="add", name="weather-api", config={
"url": "https://mcp.weather.com/...",
"headers": {"Authorization": "Bearer ${credentials.WEATHER_TOKEN}"}
})
After this call, the weather API tools appear in the agent's context. The MCP extension is dynamic — added at runtime, gated by HITL approval, fully audited, and indistinguishable from native tools in the agent's instruction.
The architecture is open. New tools can be added via MCP without changing the Facio runtime. The composability patterns still apply — MCP tools slot into pipelines, branches, and spawn calls just like native tools.
What Makes the Architecture Composable
Three architectural decisions make Facio's tool set composable where others fail:
1. Uniform interfaces. Every tool has a structured schema, a standardized error format, and the same audit trail structure. The agent learns one pattern; it applies to all 25+ tools.
2. Predictable safety. The HITL gating is consistent — destructive operations require approval, non-destructive don't. The agent knows what to expect and how to ask. The human knows what gates need attention.
3. Orthogonal capabilities. Each tool does one thing well. web_search finds URLs; web_fetch reads content; read_file reads local files; grep searches locally. The tools don't overlap. Composition emerges from non-overlap.
A counter-example: a hypothetical "do_everything" tool that searches the web, reads files, sends emails, and updates databases. It would feel powerful but compose poorly — every call to "do_everything" requires specifying which subset of capabilities to use, and the agent loses the ability to reason about each step.
Production Patterns Enabled by Composability
Pattern 1: Self-Improving Agent Loop
Agent receives task
→ read_logs → identify recent failure patterns
→ web_fetch → research best practices
→ edit_file(MEMORY.md) → update knowledge
→ write_file → generate improved workflow
→ exec → test the improvement
→ read_logs → verify improvement
→ repeat
The agent improves its own operation using six different tools, all composed into a continuous loop. No tool does "self-improvement" — but together they enable it.
Pattern 2: Multi-Format Content Pipeline
web_search + web_fetch → research material
→ write_file → draft markdown article
→ generate_image → hero image
→ generate_image → social media variants
→ exec → build static site
→ message → deliver to human for review
→ HITL → human approves
→ message → publish to channels
Seven tools, one complete content workflow. Each tool is independent; the composition produces something none of them can do alone.
Pattern 3: Infrastructure as Agent
heartbeat → trigger periodic check
→ exec → run health checks
→ read_logs → analyze results
→ manage_mcp → restart failed servers
→ switch_model → route around provider outages
→ message → alert humans to persistent issues
→ update MEMORY.md → record decisions
Six tools, one self-managing infrastructure loop. The agent becomes the operations team — continuously monitoring, diagnosing, and acting.
Bottom Line
A tool architecture isn't just a list of capabilities. It's the substrate that determines what agents can build, how they combine their capabilities, and where the safety boundaries sit. A good architecture makes composition natural; a bad one forces workarounds.
Facio's tool architecture is built for composability from the ground up: uniform interfaces, predictable safety, orthogonal capabilities, and a discovery model that scales. Twenty-five native tools plus dynamic MCP extension plus a documentation-based skill system — all following the same patterns, all respecting the same HITL boundaries, all combinable into workflows that no single tool enables.
Because the value of an agent isn't in what any one tool can do. It's in what all of them can do together.
See the tool architecture documentation for the full tool reference, composition patterns, and integration guides.