Tool Registry

El esquema de tools.json. El formato y contenido del tool registry que mapea nombres de herramientas a sus entry points.

Propósito

Esta página documenta el esquema de tools.json. El tool registry es el mecanismo que mapea nombres de herramientas a sus entry points, sus capacidades y sus tags. El registry es la lista autoritativa de herramientas disponibles para un agente.

Un ejemplo real está en {workspace-root}/movie-scraper-tools/tools.json.

Esquema

{
  "version": "string",       // versión semántica del esquema
  "tools": [                 // array de entradas de herramientas
    {
      "name": "string",        // nombre único de la herramienta
      "description": "string", // descripción de un párrafo
      "location": "string",    // ruta al entry point de la herramienta
      "status": "string",      // "ready" | "planned" | "deprecated"
      "capabilities": ["string"], // lista de nombres de capacidades
      "languages": ["string"], // lista de idiomas soportados (ISO 639-1)
      "tags": ["string"]       // lista de tags para activación de skill
    }
  ],
  "meta": {                 // metadata opcional
    "repo": "string",         // ruta al repo
    "created": "string",      // fecha ISO 8601
    "purpose": "string"       // propósito de un párrafo
  }
}

Campos

Top-level

Campo	Tipo	Requerido	Descripción
`version`	string	R	Versión semántica del esquema.
`tools`	array	R	Las entradas de herramientas.
`meta`	object	O	Metadata opcional sobre el registry.

Entrada de herramienta

Campo	Tipo	Requerido	Constraints
`name`	string	R	Nombre único de la herramienta. Lowercase, separado por guiones.
`description`	string	R	Descripción de un párrafo.
`location`	string	R	Ruta al entry point de la herramienta (relativa al registry).
`status`	string	R	`ready`, `planned` o `deprecated`.
`capabilities`	string[]	R	Lista de nombres de capacidades.
`languages`	string[]	O	Lista de idiomas soportados (ISO 639-1).
`tags`	string[]	R	Lista de tags para activación de skill.

Ejemplo

{
  "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"
  }
}

Semántica de los campos

`name`

El nombre único de la herramienta. El nombre se usa en la tabla de routing del Coordinator y en el request journal. El nombre es también el nombre del directorio bajo tools/.

Convenciones:

Lowercase.
Separado por guiones.
Sin espacios.
Singular (p. ej., torrent-finder, no torrent-finders).

`description`

Una descripción de un párrafo de qué hace la herramienta. La descripción se muestra al usuario cuando el Coordinator explica qué herramienta está usando.

`location`

La ruta al entry point de la herramienta, relativa al fichero del registry. El entry point es típicamente main.py para una herramienta CLI. La ruta es relativa al directorio que contiene el fichero tools.json.

`status`

El status de lifecycle de la herramienta:

ready — la herramienta está implementada y lista para usar.
planned — la herramienta está planeada pero no implementada.
deprecated — la herramienta ya no se mantiene.

La entrada de una herramienta planned es un placeholder. El Coordinator puede mencionar la herramienta pero no puede invocarla.

La entrada de una herramienta deprecated se mantiene por compatibilidad hacia atrás. El Coordinator no debería invocarla.

`capabilities`

La lista de capacidades que provee la herramienta. Las capacidades son las operaciones de alto nivel que la herramienta puede realizar. Por ejemplo, las capabilities de una herramienta de torrents podrían ser search y open.

Las capacidades están documentadas en el TOOL.md de la herramienta. Las capacidades son el contrato entre la herramienta y el agente.

`languages`

La lista de idiomas que soporta la herramienta. Los idiomas son códigos ISO 639-1 (p. ej., en, es, fr). El campo es opcional; las herramientas que no tienen que ver con idioma pueden omitirlo.

`tags`

La lista de tags para activación de skill. Los tags los usa el skill loader del Coordinator para encontrar la herramienta. Los tags deben ser lowercase, separados por guiones y descriptivos.

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

Validación

El tool registry se valida cuando se carga. Las comprobaciones de validación:

Todos los campos requeridos están presentes.
El name es único.
La location existe y es un fichero.
El status es uno de los valores permitidos.
Las capabilities no están vacías.
Los tags no están vacíos.

Una validación fallida se loguea, y la herramienta no se registra. El Coordinator puede ver la herramienta en el registry pero no puede invocarla.

Carga

El tool registry lo carga el Coordinator en el arranque. El orden de carga:

Carga el tools.json del proyecto.
Valida cada entrada.
Indexa las entradas por name y por tag.
Registra las entradas válidas.

El registry se recarga cuando cambia la configuración. La recarga es atómica; el registry viejo se reemplaza por el nuevo en un único paso.