Tools (Tool Registry): foundations

accepted

Status

accepted — 2026-05-09. Sector bootstrap (skeleton + 5 impl tickets) landed as part of /k-go services/ai audit wave (Modo C). Q1 resolved: tools and mcp-registry remain separate sectors with a one-way mirror (mcp-registry → tools); consumers query tools only. Q2 resolved: semver for tool versions (major iff schema-breaking; minor for new optional input; patch for behavior fix); 90-day deprecation window.

Summary

Registry de tools que agents podem chamar — separado de mcp-registry (que cataloga MCP servers, externo).

Motivation

Agents precisam descobrir quais tools existem, quais permissions exigem, qual provider. Hoje hardcoded em cada cliente. Sem registry: zero discovery, zero versioning, zero deprecation.

Scope

In

  • Tool entries (name, description, JSON schema, provider, version)
  • Permissions
  • Search
  • Depreciation flags

Out (yet)

  • Tool execution (responsabilidade do agent runtime)

Initial design

Surfaces

  • backend/ — Go API + DB
  • app/ — não aplicável v1

Key APIs

  • POST /v1/tools — registrar
  • GET /v1/tools?capability= — discovery
  • GET /v1/tools/{name}/schema — JSON schema

Dependencies

  • infra/data/kdb-doc — storage
  • services/ai/agents — consumer
  • products/dev/kode — consumer

Relation to existing sectors

  • Possível fusão com mcp-registry
  • Pré-requisito de agent ecosystem

Self-hosted-first analysis (5 gates)

  • G1 Feature parity: zero
  • G2 Performance: N/A
  • G3 Stability: N/A
  • G4 Capability: simples
  • G5 Critical-path readiness: destrava agent ecosystem

Open questions

  • Q1: Relação com mcp-registry — fundir?
  • Q2: Versioning — semver ou serial?

Next steps

  1. Ratificar esta RFC (1 round de comments).
  2. Criar sector dir services/ai/tools/ com koder.toml, README.md, skeleton.
  3. Abrir tickets de implementação em services/ai/tools/backlog/pending/.
  4. Registrar em meta/docs/stack/registries/self-hosted-pairs.md se substituir externo.