Lab NotesTooling

Tool Spec

The format and content of a TOOL.md file. The technical specification that the agent reads to understand a tool's contract.

Purpose

This page documents the format and content of a TOOL.md file. A TOOL.md is the technical specification that the agent reads to understand a tool's contract: what it does, how to invoke it, what it returns, and what can go wrong.

A TOOL.md is required for every tool in the lab. The format is consistent across all tools; this makes it easy for the agent to read a new tool's TOOL.md and know what to expect.

Required sections

Every TOOL.md must have the following sections:

  1. Title and short description.
  2. Purpose. A one-paragraph description of what the tool does.
  3. Commands. The CLI commands the tool supports.
  4. Inputs. The inputs each command takes.
  5. Outputs. The outputs each command returns.
  6. Data flow. A diagram or description of how the tool processes the inputs.
  7. Configuration. The configuration the tool requires.
  8. Dependencies. The tool's dependencies.
  9. Tests. How the tool is tested.
  10. Failure modes. What can go wrong and how to recover.

Optional sections include:

  • Examples. Usage examples.
  • Limitations. Known limitations.
  • References. Links to related docs.

Template

# Tool Spec: <tool-name>
 
## Purpose
<One-paragraph description.>
 
## Commands
 
### Command 1 (placeholder)
- Input: <args>
- Output: <output format>
- Source: <where the data comes from>
- Filters: <any filters applied>
 
### Command 2 (placeholder)
- ...
 
## Data flow
 
```text
<ASCII or mermaid diagram of the data flow.>
```
 
## Configuration
 
| Variable | Default | Purpose |
| -------- | ------- | ------- |
| ...      | ...     | ...     |
 
## Dependencies
 
- `<dependency-1>`: <version>
- `<dependency-2>`: <version>
 
## Tests
 
The tool's tests are in `tests/`. The test command is
`<test-command>`.
 
## Failure modes
 
| Failure | Result | Recovery |
| ------- | ------ | -------- |
| ...     | ...    | ...      |

Example: torrent-finder TOOL.md

A real-world example. torrent-finder searches for movies/series via BitTorrent.

# Tool Spec: torrent-finder
 
## Purpose
Search for movies/series via BitTorrent and output
magnet URLs. The Coordinator runs this to find content,
presents results, opens chosen magnet in Transmission.
 
## Commands
 
### `search <query>`
- Input: search query (movie/series name + quality
  filters)
- Output: list of magnets with source and title
- Sources: solidtorrents.net, 1377x.to, bt4g.com
- Filter results by quality: 4K, 1080p, HDR, DV,
  x265, x264
 
### `open --magnet <url>`
- Input: full magnet URL
- Output: opens in Transmission (macOS `open` command)
- Optional `--dry-run` to preview without opening
 
## Data flow
 
```text
User query (e.g., "Snatch 2000 4K")
    ↓
Build search URLs for each source
    ↓
HTTP GET with browser-like headers
    ↓
Extract magnets from HTML (regex)
    ↓
Filter by quality
    ↓
Return results
```
 
## Configuration
 
| Variable           | Default     | Purpose                          |
| ------------------ | ----------- | -------------------------------- |
| `TORRENT_SOURCES`  | (3 sources) | The sources to query.            |
| `TORRENT_TIMEOUT`  | `30`        | Per-request timeout in seconds.  |
| `TORRENT_UA`       | (random)    | The user agent string.           |
 
## Dependencies
 
- `requests>=2.28`: HTTP client.
- `beautifulsoup4>=4.11`: HTML parsing.
- `lxml>=4.9`: XML/HTML parser.
 
## Tests
 
The tests are in `tests/`. The test command is
`pytest tests/`. The tests use mocked HTTP responses to
avoid hitting the real sources.
 
## Failure modes
 
| Failure                          | Result                                  |
| -------------------------------- | --------------------------------------- |
| All sources are unreachable      | Return an empty list with a warning.    |
| No results match the query       | Return an empty list.                   |
| Source returns 4xx               | Skip the source; try the next one.      |
| Source returns 5xx               | Retry once; skip if still failing.      |
| Magnet URL is malformed          | Skip the entry; log the issue.          |

SKILL.md

The SKILL.md file is the activation file. It is loaded by the Coordinator's skill loader when the user's request matches the skill's trigger phrases.

The format is:

---
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 name and description fields in the YAML frontmatter are the trigger phrases the Coordinator uses. The body is the workflow the Coordinator follows.

Tests

The tool's tests live in tests/. The test conventions:

  • One test file per module. test_main.py for main.py, test_lib.py for lib.py, etc.
  • Use pytest. The test runner is pytest.
  • Mock external dependencies. HTTP calls, file I/O, and subprocess calls are mocked.
  • Cover the happy path and the failure paths. Every command is tested for both success and failure.
  • Use fixtures for shared setup. The conftest.py file holds the shared fixtures.

The test target is 70% coverage minimum.

Adding a new tool

To add a new tool:

  1. Copy the CLI Python tool template.
  2. Update the tool's name in all files.
  3. Implement main.py and lib.py.
  4. Write the tests.
  5. Write the README.md, TOOL.md, SKILL.md, and AGENTS.md.
  6. Register the tool in the project's tools.json.
  7. Run the tests.
  8. Verify the tool can be invoked by the Coordinator.

See also