Tooling Layer

Status

Implemented. The lab has dozens of tools across four categories: media, research, web, and code. The tooling layer is the foundation of the lab's deterministic work.

Purpose

The tooling layer converts repeatable tasks into callable capabilities. Some are local CLI-first tools; others are external service adapters exposed through MCP. In both cases, the goal is to keep the agent from depending only on generative reasoning for tasks that have a deterministic solution.

This page is the canonical reference for the tooling layer. The standard tool structure is in Tool Structure; the tool specification template is in Tool Spec; the tool registry is in Tool Registry; the media-specific tools are in Media Tools; the Media Lab Server is in Media Lab Server.

Why a tooling layer

Agents that depend only on generative reasoning for deterministic tasks are:

• Slow. A 5-second HTTP call takes 30 seconds when done through the model.
• Inconsistent. The same task produces different results on different runs.
• Expensive. Each call consumes tokens.
• Unverifiable. The output is not validated against a schema.
• Fragile. The model can hallucinate, miss steps, or pick the wrong tool.

A tooling layer addresses all five problems. The deterministic task is done by a tool, not by the model. The model's role is reduced to:

• Choosing which tool to call.
• Passing the right arguments.
• Interpreting the result.

This division of labor is the lab's core principle.

Tool categories

The lab's tools fall into four categories:

Each category has its own page with the concrete tools and their contracts.

Tool inventory

Media tools

Research tools

Web tools

Code tools

The full inventory is in the Data Dictionary.

Tool invocation

Tools are invoked through their declared interface. A tool can be invoked:

• By a CLI command. The tool's main.py (or equivalent) is the entry point.
• By an HTTP request. For HTTP-exposed tools (e.g., the Media Lab Server).
• By a Python function call. For in-process tools (e.g., the research adapters).

The tool's contract is documented in its TOOL.md and in the Tool Spec.

Tool registry

The tool registry is the framework's mechanism for exposing tools to agents. The registry is configured per agent: each agent has a list of tools it is allowed to invoke.

The registry is in the project's tools.json. A real example is at {workspace-root}/movie-scraper-tools/tools.json. The schema is documented in Tool Registry.

The registry entries reference the tool's location (the path to the tool's entry point) and its tags (for skill loader activation). The registry is the authoritative list of tools available to an agent.

Skills

A skill is a markdown file that describes a capability. The Coordinator uses the skill loader to activate relevant skills. The skill loader is in {workspace-root}/.agents/skills/.

A skill has the following structure:

---
name: skill-name
description: One-paragraph description.
---
 
# Skill Name
 
## When to Use This Skill
[Trigger phrases and conditions.]
 
## Workflow
1. Step 1
2. Step 2
3. ...
 
## Inputs
[What the skill needs.]
 
## Outputs
[What the skill produces.]
 
## Failure modes
[What can go wrong.]

The skill is loaded into the session context when the Coordinator's request matches the skill's trigger phrases. The skill's instructions are followed verbatim; the Coordinator does not modify them.

MCP adapters

Some tools are exposed through the Model Context Protocol (MCP). An MCP adapter is a server that exposes a tool's capabilities through a standardized protocol. The lab uses MCP for:

• The Perplexity adapter (the synthesis engine for P3).
• The perplexity-mcp server (documented in External Providers).

The MCP adapter's contract is documented in its README.md and in the adapter's source.

Sandbox and trust

The tools that the Coordinator can invoke run with the Coordinator's permissions. The tools that the Coding Assistant can invoke run in a sandbox with the permissions declared in the sandbox level (read-only, workspace-write, or full).

The research framework's tools run with the Scout gateway's permissions. The Media Agent's tools run with the Scout gateway's permissions (the Media Agent shares the Scout gateway).

The web tools run with the Coordinator's permissions.

The sandbox and trust levels are documented in Coding Assistant → Sandbox and trust.

Tool development

To add a new tool:

1. Pick a category. Media, research, web, or code.
2. Pick a structure. CLI tool, MCP adapter, or HTTP server.
3. Implement the tool. Follow the Tool Structure pattern.
4. Write the documentation. README.md, TOOL.md, SKILL.md, AGENTS.md.
5. Write the tests. Unit tests for the core logic.
6. Register the tool. Add an entry to tools.json.
7. Verify. Run the tests; run the smoke test.

The full template is in Project Templates → CLI Python tool template.

Tool observability

The tools are observable through:

• Logs. Every tool invocation is logged with the inputs, the outputs, the duration, and any error.
• Metrics. The tool's invocation count, error count, and duration are recorded in the metrics.
• Audit trail. The tool's invocations are recorded in the audit trail.

The observability is documented in Telemetry.

Patterns

The lab reuses a small set of patterns in the tooling layer:

Adapter pattern

The adapter pattern translates between a generic interface and a provider-specific format. The pattern is documented in External Providers → Adapter contract.

Skill pattern

The skill pattern describes a capability in a markdown file. The pattern is documented in Tool Spec.

CLI tool pattern

The CLI tool pattern wraps a deterministic capability in a Python script. The pattern is documented in Tool Structure.

HTTP server pattern

The HTTP server pattern exposes a tool through an HTTP API. The pattern is documented in Media Lab Server.

See also

• Tool Structure
• Tool Spec
• Tool Registry
• Media Tools
• Media Lab Server
• Project Templates
• External Providers
• Telemetry