Tool Registry

The `tools.json` schema. The format and content of the tool registry that maps tool names to their entry points.

Purpose

This page documents the tools.json schema. The tool registry is the mechanism that maps tool names to their entry points, their capabilities, and their tags. The registry is the authoritative list of tools available to an agent.

A real example is at {workspace-root}/movie-scraper-tools/tools.json.

Schema

{
  "version": "string",       // semantic version of the schema
  "tools": [                 // array of tool entries
    {
      "name": "string",        // unique tool name
      "description": "string", // one-paragraph description
      "location": "string",    // path to the tool's entry point
      "status": "string",      // "ready" | "planned" | "deprecated"
      "capabilities": ["string"], // list of capability names
      "languages": ["string"], // list of supported languages (ISO 639-1)
      "tags": ["string"]       // list of tags for skill activation
    }
  ],
  "meta": {                 // optional metadata
    "repo": "string",         // path to the repo
    "created": "string",      // ISO 8601 date
    "purpose": "string"       // one-paragraph purpose
  }
}

Fields

Top-level

Field	Type	Required	Description
`version`	string	R	Semantic version of the schema.
`tools`	array	R	The tool entries.
`meta`	object	O	Optional metadata about the registry.

Tool entry

Field	Type	Required	Constraints
`name`	string	R	Unique tool name. Lowercase, hyphen-separated.
`description`	string	R	One-paragraph description.
`location`	string	R	Path to the tool's entry point (relative to the registry).
`status`	string	R	`ready`, `planned`, or `deprecated`.
`capabilities`	string[]	R	List of capability names.
`languages`	string[]	O	List of supported languages (ISO 639-1).
`tags`	string[]	R	List of tags for skill activation.

Example

{
  "version": "1.0.0",
  "tools": [
    {
      "name": "torrent-finder",
      "description": "Search and download movies/series via BitTorrent",
      "location": "tools/torrent-finder/main.py",
      "status": "ready",
      "capabilities": ["search", "open"],
      "languages": ["en", "es"],
      "tags": ["torrent", "movies", "series", "4k", "1080p"]
    },
    {
      "name": "subtitle-finder",
      "description": "Search and download subtitles in Spanish",
      "location": "tools/subtitle-finder/main.py",
      "status": "ready",
      "capabilities": ["search", "download"],
      "languages": ["es", "en"],
      "tags": ["subtitles", "srt", "español"]
    },
    {
      "name": "dubbed-finder",
      "description": "Identify if a release has Spanish dubbed audio",
      "location": "tools/dubbed-finder/main.py",
      "status": "ready",
      "capabilities": ["check", "search"],
      "languages": ["es"],
      "tags": ["dubbed", "castellano", "audio"]
    },
    {
      "name": "media-info",
      "description": "Extract technical info from media files",
      "location": "tools/media-info/main.py",
      "status": "ready",
      "capabilities": ["info", "tracks", "quick"],
      "tags": ["ffprobe", "codec", "resolution", "audio-tracks"]
    }
  ],
  "meta": {
    "repo": "{workspace-root}/movie-scraper-tools/",
    "created": "2026-05-09",
    "purpose": "Kone's local movie/series scraping automation toolkit"
  }
}

Field semantics

`name`

The tool's unique name. The name is used in the Coordinator's routing table and in the request journal. The name is also the directory name under tools/.

Conventions:

Lowercase.
Hyphen-separated.
No spaces.
Singular (e.g., torrent-finder, not torrent-finders).

`description`

A one-paragraph description of what the tool does. The description is shown to the user when the Coordinator explains what tool it is using.

`location`

The path to the tool's entry point, relative to the registry file. The entry point is typically main.py for a CLI tool. The path is relative to the directory that contains the tools.json file.

`status`

The tool's lifecycle status:

ready — the tool is implemented and ready to use.
planned — the tool is planned but not implemented.
deprecated — the tool is no longer maintained.

A planned tool's entry is a placeholder. The Coordinator can mention the tool but cannot invoke it.

A deprecated tool's entry is kept for backwards compatibility. The Coordinator should not invoke it.

`capabilities`

The list of capabilities the tool provides. The capabilities are the high-level operations the tool can perform. For example, a torrent tool's capabilities might be search and open.

The capabilities are documented in the tool's TOOL.md. The capabilities are the contract between the tool and the agent.

`languages`

The list of languages the tool supports. The languages are ISO 639-1 codes (e.g., en, es, fr). The field is optional; tools that do not deal with language can omit it.

`tags`

The list of tags for skill activation. The tags are used by the Coordinator's skill loader to find the tool. The tags should be lowercase, hyphen-separated, and descriptive.

Examples of tags: torrent, movies, series, 4k, 1080p, subtitles, srt, español, dubbed, castellano, audio, ffprobe, codec, resolution.

Validation

The tool registry is validated when it is loaded. The validation checks:

All required fields are present.
The name is unique.
The location exists and is a file.
The status is one of the allowed values.
The capabilities are non-empty.
The tags are non-empty.

A failed validation is logged, and the tool is not registered. The Coordinator can still see the tool in the registry but cannot invoke it.

Loading

The tool registry is loaded by the Coordinator at startup. The loading order:

Load the project's tools.json.
Validate each entry.
Index the entries by name and by tag.
Register the valid entries.

The registry is reloaded on configuration change. The reload is atomic; the old registry is replaced by the new one in a single step.