The Governed Tool Registry
Agents don't get a browser and a prayer. They get a registry.
Every external capability in Escepine—search, crawl, scrape, fetch, and assemble—is exposed through a registered tool. Each entry defines a name, version, typed payload schema, Cedar action binding, timeout, retry policy, and failure contract.
There is exactly one execution path from an agent to the outside world: the governed tool registry. This centralized control point is where authorization is evaluated and execution evidence is recorded. A tool call that bypasses either step is not a valid execution path.
This document defines the registry entry schema, catalogs the tools referenced throughout the documentation, and explains the structural constraint that makes the Cedar policies on the Cedar Policies page enforceable.
- Registry Entry Schema
Every registry entry is validated at load time. A malformed entry is a deployment error, not a runtime surprise.
The following example illustrates a registered tool entry:
{ "name": "firecrawl_scrape", "version": "1.2.0", "description": "Read a single public page and return its rendered content.", "cedar_action": "Action::"firecrawl_scrape"", "payload_schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": ["url"], "additionalProperties": false }, "accepts_credentials": false, "timeout_ms": 30000, "retry": { "max_attempts": 3, "backoff_ms": 2000 }, "on_failure": [ "halt", "halt_and_escalate", "compensate" ] }
1.1 Schema Enforcement
Two properties are particularly important to the registry's security model:
additionalProperties: false — Rejects payloads containing fields that are not explicitly declared in the schema. In strict validation mode, unknown fields are invalid. accepts_credentials: false — Documents the tool's credential-free contract. The structural guarantee comes from the payload schema itself: no declared field accepts a username, password, session cookie, or target-site API key.
A configuration flag alone does not prevent an agent from constructing an unsupported field. Strict schema validation makes that field invalid.
This design establishes the structural foundation for the Cedar policies described in the Cedar Policies reference.
- Registered Tools
The registry is the source of truth for available capabilities. The following table summarizes the entries referenced throughout this documentation.
Tool Cedar Action Payload Purpose firecrawl_scrape Action::"firecrawl_scrape" url: string Read one public page per call. tavily_search Action::"tavily_search" query, max_results Discover public sources. tavily_crawl Action::"tavily_crawl" query, max_results Map a target's public footprint. web_fetch_exa Action::"web_fetch_exa" urls: string[] Bulk-fetch previously vetted URLs. deliverable_assemble Action::"deliverable_assemble" format, include_evidence_index Assemble the final deliverable and its evidence index.
Each tool has a distinct payload contract and a corresponding Cedar action. These are not merely implementation details: the shape of a payload determines which attributes the policy engine can inspect.
The distinction between a single URL and a list of URLs is especially significant and is explained in Section 4.
- Structural Security: No Credentials
No governed tool accepts credentials.
This restriction covers usernames, passwords, session cookies, and API keys intended for authentication against target websites. These fields are absent from the registered payload schemas, leaving no supported input through which an agent can supply them.
3.1 Wrapper Denial
This design is an essential component of wrapper denial: restricting an agent's capabilities through the interface that mediates its access to external systems.
For example, the Cedar policies described in the Cedar Policies reference can deny access to linkedin.com. The credential-free tool contract provides a complementary safeguard: even if an agent attempts to bypass a restriction by logging in, the governed interface provides no supported credential fields.
The two controls serve different purposes:
Policy enforcement determines which actions and resources are permitted. Schema enforcement restricts the inputs that an agent can submit to a tool.
Together, these controls reduce reliance on the model's willingness to follow instructions. A policy that merely prohibits an operation depends on the enforcement layer to reject it; a schema that cannot represent the required inputs removes an entire class of execution paths.
- Payload Shape Is a Policy Decision
Cedar's like operator performs pattern matching against strings. It does not recursively inspect a list and apply a string pattern to every element.
This limitation directly influences how tools are designed and selected.
4.1 Single-URL Scraping
The firecrawl_scrape tool accepts exactly one URL:
{ "url": "https://example.com/public-page" }
Because each invocation contains a single URL, the policy engine can evaluate that URL as part of the authorization decision for each page read.
This makes the tool suitable for workflows that require resource-level URL inspection.
4.2 Bulk URL Fetching
The web_fetch_exa tool accepts a list of URLs:
{ "urls": [ "https://example.com/page-a", "https://example.org/page-b" ] }
This interface supports bulk fetching, but it introduces a policy-inspection limitation: Cedar cannot use like to pattern-match each URL inside the list individually.
The policy engine may inspect the list as an attribute, but that is not equivalent to evaluating every URL against a string pattern.
4.3 Routing Rule
When a standard operating procedure (SOP) requires individual URL-level policy evaluation, it must route page reads through firecrawl_scrape, even when web_fetch_exa could perform the same work more efficiently.
Payload design determines what the policy engine can inspect. Tool selection must preserve the granularity required by the security policy.
Performance optimizations must not silently weaken policy enforcement.
- Tool Execution Lifecycle
Every EXECUTION step in every SOP follows the same governed sequence.
Resolve the tool. The runtime looks up the requested tool in the registry. An unknown tool halts the run; it is never executed as an unregistered fallback. Validate the payload. The runtime validates the submitted payload against the registered schema. Missing required fields, unsupported fields, and other schema violations make the payload invalid. Authorize the action. Cedar evaluates the principal, action, resource attributes, and applicable policy context. A DENY is an authorization decision, not a transient execution error, and must not be retried as though it were a network failure. Execute the tool. The runtime enforces the configured timeout and retry budget. Record evidence. Execution evidence is written before control returns to the state machine. Advance the state machine. The workflow proceeds only along transitions declared by the SOP.
This sequence ensures that tool resolution, input validation, authorization, execution, and evidence recording remain part of one governed execution path.
- Failure Handling and Retry Semantics
Each registry entry declares its execution limits and failure contract.
Setting Responsibility timeout_ms Defines the maximum execution time allowed for a tool call. retry.max_attempts Limits the number of execution attempts. retry.backoff_ms Defines the configured delay between retry attempts. on_failure Declares the supported failure-handling outcomes.
The example registry entry defines three possible failure outcomes:
halt — Stop the current execution path. halt_and_escalate — Stop execution and escalate the failure for further handling. compensate — Invoke an applicable compensating procedure when the workflow supports one.
Authorization failures must remain distinct from operational failures. A Cedar denial must not trigger retries intended for recoverable conditions such as transient network errors.
The runtime must also ensure that retries do not violate the evidence-recording contract or repeat side effects without an appropriate safety mechanism.
- Relationship to SOPs and Skills
The registry defines the boundary of what an agent can execute. Higher-level workflow components compose registered capabilities rather than creating independent paths to external systems.
Tool registry: Defines available capabilities, payload contracts, authorization bindings, and execution constraints. SOPs: Define workflow steps, execution order, failure handling, and permitted state transitions. Skills: Organize reusable capabilities and workflow logic around the registered tools.
See the SOP Reference and Skills Reference for details on how these higher-level components use the registry.
- Design Principles
The governed tool registry is built around five principles:
Explicit capabilities: Every external operation must be registered before it can execute. Strict input contracts: Every payload must conform to its declared schema. Policy-aware interfaces: Payload shapes must preserve the granularity required for authorization. Credential-free execution: Governed tools must not expose credential inputs for authenticating to target systems. Auditable execution: Evidence must be recorded before control returns to the workflow state machine.
These principles make the registry more than a catalog of tools. It is the enforcement boundary between an agent's intentions and its permitted external actions.
The ceiling of what an agent can do is determined by the capabilities exposed through the registry and the controls enforced around them—not by the model's ability to invent new actions.