Skip to content

ADR-0010: AI Tool Registry and Manifest Discovery

Status

ACCEPTED

Date: 2026-02-14

Changelog

Date Revision Description Author
2026-02-14 1.0 Initial version souperk
2026-02-15 1.1 Update status to reflect implementation souperk

Implementation Status

Data model and catalog revision infrastructure are implemented. Tool sources, tools, and catalog revisions are fully modeled with entities, repositories, and services. Content-hash-based catalog revisions are created on refresh, and runs pin to a specific catalog revision.

Not yet implemented: - HTTP fetching of manifests from tool sources (currently stubbed) - No real tool source services are registered yet

Context

The AI service requires a mechanism to discover and register external tools that the LLM can invoke during orchestration runs. Tools are hosted by other Loryth services (e.g., grocery, issues, kb) and must be made available to the model as JSON Schema function definitions.

Key factors influencing this decision: - Tools are owned and deployed independently by their respective services - The AI service needs a consistent view of available tools for each run - Tool definitions may change between deployments (parameters added/removed, descriptions updated) - Runs must be reproducible: the exact set of tools used in a run must be determinable after the fact - V1 needs to be simple and operational quickly; more sophisticated discovery can come later

Decision

We will implement a config-seeded tool registry with content-hash-based catalog revisions:

  1. Tool Sources: Each external service that exposes tools is registered as a ToolSource with a manifest_url pointing to a well-known endpoint (e.g., GET /tools/manifest). Tool sources are seeded from application configuration at startup.

  2. Manifest Format: Each tool source returns a JSON array of tool definitions, each containing tool_id, name, description, and parameters_schema (JSON Schema).

  3. Refresh Cycle: An admin endpoint (POST /admin/tools/refresh) triggers the AI service to pull manifests from all active tool sources, upsert tools, and compute a SHA-256 content hash over the sorted, canonical tool set.

  4. Catalog Revisions: When the content hash changes after a refresh, a new ToolCatalogRevision is created with an incrementing revision_number and the computed content_hash. This provides an immutable snapshot of the tool catalog at a point in time.

  5. Run Pinning: When a run is created, the current catalog_revision_id is recorded on the Run entity. This ensures the run's tool set is frozen and auditable regardless of later tool changes.

  6. No Auto-Discovery in V1: There is no service mesh introspection or dynamic registration. Tool sources are explicitly configured. This is a deliberate simplification for the initial version.

Consequences

Positive

  • Simple to implement and reason about: tool sources are explicit configuration
  • Content-hash revisions provide cheap change detection without diffing individual tools
  • Run pinning guarantees reproducibility and auditability of tool usage
  • Refresh is idempotent and safe to call repeatedly (no-op if hash unchanged)

Negative

  • Manual configuration required when adding new tool sources
  • No real-time tool discovery: changes are only detected on explicit refresh
  • Manifest endpoint must be implemented by each service that wants to expose tools

Neutral

  • Future versions may add event-driven refresh (tool source publishes change event via RabbitMQ)
  • Future versions may add service mesh discovery to auto-detect tool sources
  • The content hash approach scales well to hundreds of tools but may need partitioning for thousands

Alternatives Considered

  1. Service Mesh Auto-Discovery
  2. Description: Use Consul/etcd service tags or DNS SRV records to auto-discover tool-providing services
  3. Pros: Zero-config for new tool sources, always up to date
  4. Cons: Requires service mesh infrastructure not currently in place, complex failure modes, overkill for current service count

  5. Why not chosen: Premature infrastructure investment for a platform with < 10 services

  6. Event-Driven Tool Sync

  7. Description: Tool sources publish events when their tool definitions change; AI service consumes and updates
  8. Pros: Near-real-time updates, decoupled from polling
  9. Cons: Requires each service to implement event publishing for tool changes, adds messaging complexity

  10. Why not chosen: Good future enhancement but unnecessary complexity for V1 where tools change infrequently

  11. Static Tool Definitions in AI Service Config

  12. Description: Embed tool JSON schemas directly in the AI service configuration files
  13. Pros: Simplest possible approach, no network calls
  14. Cons: Tool definitions duplicated across services, no single source of truth, manual sync burden
  15. Why not chosen: Violates ownership principle; tool-providing services should be the authority on their tool schemas

References