Layer 6 of 12·Slice: Infrastructure services·Platform: No dedicated platform

Scope of this page. Reference material for the Tool Abstraction layer: what it owns, what it must not own, and how Synedrix OS implements it today. It is descriptive, not normative — where this page and the Layer Taxonomy Table disagree, the taxonomy table wins.

What this layer is

Tool Abstraction normalizes how an agent reaches an external system. Every capability an agent may invoke — a database read, a write to canonical state, a search call, a cross-agent delegation — passes through this layer as a named, typed tool rather than as a direct integration the agent’s reasoning code holds a handle to. The layer’s job is to make that access uniform: one tool identifier convention, one authorization model, one enforcement point, regardless of which system sits behind the adapter or which runtime engine is calling it.

This is a normalization layer, not a reasoning layer. It does not decide whether a tool call is a good idea — that judgment belongs to the agent’s model and, for anything with a side effect, to Governance (Layer 9). It does not decide who is allowed to see a UI or approve a request — that is Human Interface (Layer 1). What Tool Abstraction owns is narrower and load-bearing: the contract a tool call must satisfy before it is allowed to reach the system it targets, and the enforcement of that contract at the moment of invocation, not before.

flowchart LR
  n1([Tool Abstraction]):::term
  subgraph What it owns
    n2[Adapters]:::agent
    n3[Tool contracts]:::agent
    n4[Permission scopes]:::agent
    n5[Retries]:::agent
  end
  n1 --> n2
  subgraph What it must not own
    n6[Domain decision logic]:::warn
    n7[Domain Pack Layer]:::term
    n6 --> n7
    n8[Human interface concerns]:::warn
    n9[Human Interface Layer]:::term
    n8 --> n9
    n10[Domain-specific policies]:::warn
    n11[Domain Pack Layer]:::term
    n10 --> n11
  end
  n1 --> n6
  subgraph Interfaces with
    n12[Agent Runtime]:::check
    n13[Governance Controls]:::check
    n14[Observability]:::check
  end
  n1 --> n12

What it owns

Per the Layer Taxonomy Table, Tool Abstraction owns the mechanics of normalized, permissioned access to external systems. Concretely, that means:

  • Adapters — the per-system integration code that turns a tool call into a concrete API request
  • Tool contracts — the canonical tool_id convention (tool:<provider>-<verb>) and the input/output shape each tool exposes
  • Permission scopes — the capability ceiling, runtime restriction and instance override that together resolve which tools an agent may call for a given invocation
  • Retries — tool-call-level retry and timeout behaviour distinct from workflow-level retry

What it must not own

This layer adapts and authorizes; it does not decide or present. The taxonomy table draws that line explicitly, and the corresponding capability lives in a different layer.

ConcernCorrect owner
Domain decision logicDomain Pack Layer
Human interface concernsHuman Interface Layer
Domain-specific policiesDomain Pack Layer

Interfaces with

Tool Abstraction sits between the agent that wants to act and the systems it acts on, which puts it in the path of three other layers on every call:

  • Agent Runtime (Layer 4) — the LangGraph executor and the n8n AI Agent node are the two places a resolved active tool set is actually enforced; the runtime is the caller this layer authorizes for.
  • Governance & Controls (Layer 9) — write-capable and MCP/A2A-backed tool calls are submitted to Policy Guard (os-agt-002) before execution; this layer carries the policy decision, it does not make it.
  • Observability (Layer 10) — every authorization outcome (agent.tool.authorized, .unauthorized, .suspended, and the MCP/A2A approval events) is traced to Langfuse and the event bus, so a tool call’s authorization path is reconstructible after the fact.

How Synedrix OS implements it

Three canonical documents carry this layer’s real specification.

The Tool Authorization Model is the conceptual foundation. Every tool is a named, typed capability under the tool:<provider>-<verb> convention (tool:supabase-write, tool:searxng-search). An agent’s capability ceiling — declared once in its Agent Spec tool_permissions and immutable at runtime — is the hard upper bound on what it may ever call; no runtime policy or business-instance configuration can add a tool beyond it. From that ceiling, orchestration (n8n, Layer 3) computes the active tool set for a specific invocation by applying three layers of restriction in strict order — capability ceiling → runtime restriction (tool_authorization_policy’s all / declared / restricted modes) → instance override (business-instance environment_overrides) — each layer only able to narrow what came before it. The resolved active tool set is what the LLM actually sees; a tool absent from it is invisible to the model, not merely denied. Enforcement happens at two points depending on runtime engine: structurally, via connected sub-nodes, for n8n AI Agent hosts, and programmatically, inside a conditional edge before ToolNode executes, for LangGraph — both reject a call before execution and emit agent.tool.unauthorized.

The Agent Runtime Policy Spec is the authoritative schema for tool_authorization_policy, including the mcp_tool_policy and a2a_tool_policy blocks that govern protocol-backed tools specifically — MCP server allow/deny-listing, mcp_write_approval_required (default true), A2A trust tiers (trusted / provisional / untrusted) and partner allowlists. It also fixes the OS/domain-pack/business-instance split for tool authorization: the OS owns the tool_permissions schema and the ceiling rule, domain packs declare the tool capability set per domain agent, and business instances may only further restrict — never widen — the active set per environment.

The Interoperability Protocol Strategy positions MCP as the protocol Synedrix OS adopts at this layer — “the tool abstraction boundary, not the orchestration core.” MCP tools are exposed read-first, with write-capable tools introduced only once approval and permission semantics are clear, and every MCP-exposed tool call is routed through the same governance and observability controls as a native adapter call. A2A, by contrast, is adopted at the platform edge for agent-to-agent interoperability and is governed at the Agent Runtime layer rather than here — this layer’s role in the A2A story is limited to treating an A2A-backed tool invocation like any other tool subject to the ceiling and the three-layer resolution.

Platform mapping

Tool Abstraction has no discrete platform row in the Layer Taxonomy Table’s platform mapping — no single product occupies this layer the way n8n occupies Orchestration or Qdrant occupies part of Memory & Data. The layer is realized instead through two canonical specifications: the Tool Authorization Model, which defines the resolution and enforcement mechanics, and the MCP protocol boundary described in the Interoperability Protocol Strategy. Concrete adapters live inside the n8n and LangGraph implementations that call through this layer, not as a separate platform in the stack.

OS agents at this layer

No OS-owned agent is assigned to Tool Abstraction in the Agent Registry. This is deliberate rather than an oversight: Tool Abstraction is a normalization layer every agent calls through on its way to a system, not a layer where an agent reasons or reaches decisions. The registry assigns OS agents only to Layers 3, 4, 5, 7, 9 and 10 — the layers where sequencing, execution, capability discovery, memory, governance and observability decisions are actually made. A tool call’s authorization outcome may trigger Policy Guard (os-agt-002, Layer 9) approval, but Policy Guard’s home layer is Governance & Controls, not Tool Abstraction.

Layer principles that apply

Two of the taxonomy table’s layer principles bear directly on this layer:

  • 3. Tools are adapters, not business logic — external systems must be accessed through normalized adapters so domain packs do not become tightly coupled to vendor APIs; this is this layer’s reason for existing.
  • 2. Controls before execution — the three-layer tool authorization model and the MCP/A2A approval gates are exactly this principle applied to tool calls: every write-capable or protocol-backed call passes through governance before it reaches the system it targets, rather than bypassing it for convenience.

Synedrix OS · Layer reference · Tool Abstraction