EAAPLEnterprise AI Architecture Pattern Library
EAAPLLibraryAgentic AIEAAPL-AGT003
EAAPL-AGT003Proven
⇄ Compare

Agent Tool Registry

🤖 Agentic AIEU AI ActISO/IEC 42001

[EAAPL-AGT003] Agent Tool Registry

Category: Agentic AI Sub-category: Tool Management Infrastructure Version: 1.3 Maturity: Proven Tags: tool-registry, tool-discovery, capability-routing, tool-versioning, access-control, audit-logging Regulatory Relevance: EU AI Act (Art. 9, 14), ISO 42001 §8.4, NIST AI RMF (GOVERN 1.6, MANAGE 2.4), APRA CPS 234


1. Executive Summary

The Agent Tool Registry Pattern defines the centralised catalogue and invocation framework through which AI agents discover, select, and execute tools — the external capabilities (APIs, databases, code executors, search engines) that give agents the ability to act on the world. Without a registry, each tool integration is bespoke: hardcoded into the agent, undiscoverable by other agents, unmonitored for health, and impossible to govern as a portfolio.

For CIO/CTO audiences: the Tool Registry is the API management layer for your AI workforce. Just as an enterprise API gateway governs which services your applications can call, the Tool Registry governs which capabilities your AI agents can invoke. It enforces access controls, logs every invocation for audit, monitors tool health, and manages tool versions — preventing agents from calling deprecated tools that contain known vulnerabilities or incorrect business logic. Done well, it reduces new tool onboarding time from weeks (per-agent integration) to hours (register once, available to all authorised agents), and gives governance teams a single pane of glass for the actions AI agents can take in your enterprise.


2. Problem Statement

Business Problem

As an organisation's AI agent portfolio grows, the proliferation of bespoke tool integrations creates an unmanageable risk surface. Security teams cannot enumerate what external systems agents can reach. Audit teams cannot produce evidence of what actions were taken. Operators cannot identify which agents call a deprecated tool before it is retired. New agents cannot discover existing capabilities and duplicate integrations unnecessarily.

Technical Problem

Without a registry, tool definitions live inside individual agent codebases. There is no canonical schema for what a tool is, what it accepts, and what it returns. No health monitoring detects when a downstream API is degraded. No version management prevents agents from calling a tool whose contract has changed. No access control matrix prevents a low-privilege agent from calling a high-privilege tool.

Symptoms of Absence

  • Duplicate tool implementations exist across multiple agent codebases with slight inconsistencies
  • A downstream API change silently breaks multiple agents because there is no impact analysis capability
  • Security audit cannot produce a complete list of external systems accessible via AI agents
  • No aggregate view of tool call failure rates; problems are discovered by users, not operators
  • New agent developers re-implement integrations that already exist because they have no discovery mechanism

Cost of Inaction

  • Security: Ungoverned tool proliferation creates an expanding, invisible attack surface
  • Operational: Tool changes break multiple agents simultaneously without notice
  • Audit: Inability to produce complete tool call logs is a material finding under APRA CPS 234
  • Engineering: Re-implementation of existing integrations wastes 20–40% of agent development time

3. Context

When to Apply

  • The organisation operates ≥2 agents that share one or more common tool capabilities
  • Regulatory or audit requirements demand a complete log of all agent-initiated external actions
  • Tool health monitoring is needed to detect and route around degraded downstream services
  • Multiple teams are developing agents independently and need a governed capability sharing mechanism
  • Tool access control (some agents can call certain tools, others cannot) is required

When NOT to Apply

  • Single-agent, single-tool proof-of-concept with no anticipated scale
  • The agent framework already provides a first-class registry implementation that meets security and governance requirements (evaluate before building a custom registry)
  • Tools are so simple and stable that the overhead of registry management exceeds the benefit

Prerequisites

  • Agent identity framework (EAAPL-AGT009) to scope per-agent permissions
  • Tool sandboxing capability (EAAPL-AGT004) for executing tool code in isolation
  • Observability infrastructure for tool call metrics and traces
  • A tool definition standard (JSON Schema-based, see Section 6)

Industry Applicability

Industry Tool Registry Priority Key Tool Types Governance Requirement
Financial Services Critical Core banking APIs, trading APIs, regulatory reporting systems, payment gateways Very High — MiFID II, CPS 234
Healthcare Critical EHR systems, prescription systems, imaging systems Very High — HIPAA, My Health Record
Government High Case management systems, payment systems, identity verification High — APS data governance
Technology High Cloud APIs, CI/CD systems, monitoring systems Medium — SOC 2
Retail Medium OMS, WMS, CRM, payment terminals Medium

4. Architecture Overview

The Tool Registry is an enterprise service — not a library inside an agent. This distinction matters architecturally: the registry runs as its own service with its own availability SLA, its own deployment lifecycle, and its own governance controls. Agents call the registry at startup (to load their permitted tool set) and at runtime (for dynamic discovery and health checks). The registry never executes tools directly; it serves definitions and manages invocation metadata.

Why a centralised registry rather than agent-local tool configuration? The answer is governance at scale. When tools are defined locally in each agent, there is no single point at which to enforce access controls, monitor health, or manage versions. A centralised registry imposes a contract: every tool must be registered before any agent can call it, every registration must include complete metadata (schema, access tier, owner, SLA), and every invocation is logged at the registry level regardless of what the agent records.

Tool Definition Schema At the core of the registry is the Tool Definition — a structured JSON document that fully describes a tool's interface and governance metadata. The schema includes: tool_id (globally unique), name and description (for capability-based discovery), input_schema (JSON Schema for argument validation), output_schema, access_tier (public/restricted/privileged), owner_team, SLA (target latency, availability), sandbox_requirements, idempotency flag, side_effect_class (read-only/idempotent-write/destructive), rate_limit, and required_capabilities (the permission labels an agent must hold to invoke this tool).

Tool Discovery Agents discover tools in two modes. Static discovery happens at agent startup: the registry returns the agent's full permitted tool set based on its identity and capability grants. Dynamic discovery happens at task time: an agent can query the registry by capability description (natural language or tag-based) to find tools that match an emerging need. This enables agents to be built against stable capability contracts rather than specific tool IDs, making tool upgrades and replacements transparent to agent logic.

Capability-Based Tool Selection Rather than hardcoding tool names, sophisticated agents can query the registry for the best available tool for a capability class (e.g., "search the enterprise knowledge base," "read a customer account," "send a notification"). The registry returns a ranked list of tools that match the capability, ordered by health score, latency SLA, and the agent's access tier. This indirection enables tool upgrades without agent redeployment.

Tool Versioning Every tool definition is versioned. When a tool's API contract changes, the new version is registered alongside the old. The registry enforces a deprecation lifecycle: deprecated tools are flagged in discovery responses and their invocations generate deprecation warnings in the audit log. A migration period (default: 30 days) allows agents to be updated before the old version is retired. The registry impact analysis API returns which agents are still calling a version under deprecation, enabling targeted remediation.

Tool Health Monitoring The registry runs a synthetic probe against each tool on a configurable schedule (default: every 60 seconds). The probe measures latency and success rate. The registry maintains a per-tool health score that is factored into capability-based selection. When a tool's health score falls below a threshold, the registry can mark it as degraded and suggest alternatives in discovery responses. This allows agents to automatically route around failing tools without re-deployment.

Invocation Lifecycle When an agent dispatches a tool call, the Tool Dispatcher validates the call against the registry-provided schema (JSON Schema validation), checks the agent's capability grants, records a pre-invocation audit record, executes the tool in the sandbox, and records the post-invocation result. The registry serves as the authority for what is permitted; the sandbox serves as the authority for isolation; the audit log serves as the authority for what happened.


5. Architecture Diagram

ARCHITECTURE DIAGRAM
flowchart TD subgraph Agent["Agent Runtime"] A[AI Agent] B[Tool Dispatcher] end subgraph Registry["Tool Registry Service"] C[Registry API] D[(Tool Catalog)] E[Health Monitor] end subgraph Execution["Execution Layer"] F[Sandboxed Executor] G[Registered Tools] end A -->|discover capabilities| C C -->|definitions + ACL| D B -->|validate + invoke| F D -->|schema + access rules| B E -->|health scores| D E -->|synthetic probe| G F -->|execute| G G -->|result| B B -->|audit record| D style A fill:#dbeafe,stroke:#3b82f6 style B fill:#f0fdf4,stroke:#22c55e style C fill:#f0fdf4,stroke:#22c55e style D fill:#fef9c3,stroke:#eab308 style E fill:#f0fdf4,stroke:#22c55e style F fill:#f0fdf4,stroke:#22c55e style G fill:#d1fae5,stroke:#10b981

6. Components

Component Type Responsibility Technology Options Criticality
Registry API Service Interface Serves tool definitions, handles discovery queries, manages registrations REST + gRPC; FastAPI, Go net/http, Azure API Management Critical
Tool Catalog Data Store Stores all tool definitions, versions, metadata, health scores PostgreSQL (primary), Redis (read cache) Critical
Discovery Engine Query Service Capability-based tool search; natural language and tag-based matching; returns ranked results Elasticsearch or pgvector for semantic search + metadata filter High
Schema Validator Validation Library Validates agent-supplied tool arguments against tool's JSON Schema before invocation jsonschema (Python), ajv (JS/TS), JSON Schema validator Critical
Access Control Checker Security Service Validates agent capability grants against tool access requirements OPA (Rego policies), RBAC middleware, custom policy engine Critical
Health Monitor Background Service Synthetic probes per registered tool; computes health score; updates catalog Custom scheduler + HTTP client; AWS CloudWatch Synthetics High
Version Manager Lifecycle Service Tracks tool versions; enforces deprecation lifecycle; generates impact analysis Custom + catalog queries; semantic versioning High
Tool Dispatcher Orchestration Coordinates validation, auth check, sandbox invocation, result handling, audit Part of agent runtime; LangChain, Semantic Kernel, custom Critical
Sandboxed Executor Compute Executes tool in isolation (see EAAPL-AGT004) Docker, Firecracker, Lambda, Cloud Run Critical
Audit Log Compliance Immutable record of all tool invocations WORM storage: S3 Object Lock, Azure Immutable Blob Critical
Metrics Dashboard Observability Per-tool call rates, error rates, latencies, deprecation usage Grafana + Prometheus, Datadog, Azure Monitor High
Deprecation Alert System Operations Notifies tool owners and agent developers of pending deprecations PagerDuty, email, Slack webhook Medium
Identity Store Security Agent identity and capability grants source-of-truth OIDC/OAuth provider, Azure AD, AWS IAM Critical

7. Data Flow

Tool Registration Flow

Step Actor Action Output
1 Tool Developer Submits tool definition: id, name, description, input_schema, output_schema, access_tier, owner, SLA, sandbox_requirements, side_effect_class, rate_limits Tool registration request
2 Registry API Validates definition completeness; checks for id uniqueness; validates JSON Schema syntax Validated definition or validation error
3 Version Manager Assigns version number; checks for contract changes vs. prior version Versioned tool definition
4 Tool Catalog Writes tool definition; initialises health score to 0 (unchecked) Tool record written
5 Health Monitor Immediately probes new tool (if probe endpoint provided) Initial health score set
6 Audit Log Records registration event: tool_id, version, owner, access_tier, registrar_identity, timestamp Audit entry

Tool Discovery + Invocation Flow

Step Actor Action Output
1 Agent Sends discovery query: capability description or tags; agent identity token Capability query
2 Discovery Engine Semantic search over tool descriptions and tags; filters by agent's access tier; ranks by health score + SLA Ranked tool list
3 Agent Selects tool; prepares arguments Tool call intent: {tool_id, version, arguments}
4 Tool Dispatcher Fetches tool schema from cache/catalog Tool definition
5 Schema Validator Validates arguments against input_schema; returns errors if invalid Validated arguments or validation error
6 Access Control Checker Verifies agent capability grants include the tool's required_capabilities Approved or access denied
7 Audit Log Writes pre-invocation record: task_id, agent_id, tool_id, version, argument hash, timestamp Pre-invoke audit entry
8 Sandboxed Executor Executes tool with validated arguments; enforces resource quotas Tool result or error
9 Tool Dispatcher Normalises result; checks for deprecation warning Structured result
10 Audit Log Writes post-invocation record: result hash, latency, success/error code, timestamp Post-invoke audit entry
11 Metrics Records latency, result code per tool_id Metric data point

Error Flow

Error Detection Recovery
Schema validation failure Schema Validator Return structured error to agent; agent may reformulate arguments
Access denied Access Control Checker Return 403 with denied_capability detail; agent cannot escalate without explicit approval
Tool execution timeout Sandboxed Executor Return timeout error; agent can retry or try alternative tool from discovery results
Tool health below threshold Health Monitor Discovery engine deprioritises degraded tool; may return alternative in ranked list
Deprecated tool called Version Manager flag in catalog Return result with deprecation warning header; log deprecation usage metric

8. Security Considerations

Access Control

  • Every tool has an access_tier: PUBLIC (any agent), RESTRICTED (agents with specific capability grants), PRIVILEGED (agents with explicit human-approved elevated grants)
  • Tool capability grants are assigned to agent identities via the identity store; an agent cannot self-grant capabilities
  • The access control check is enforced at the registry service, not in the agent — agents cannot bypass it

Audit and Non-Repudiation

  • Pre- and post-invocation audit records create a non-repudiable evidence chain for every tool action
  • Argument hashes (not raw arguments, to protect sensitive data) are stored in the audit log; raw arguments are stored in a classified log accessible only to authorised investigators
  • Audit records are signed with a service key; tampering is detectable

Supply Chain Security

  • Tools are registered with a hash of the implementing code or container image; the health monitor validates the hash on each probe
  • Third-party tool implementations (e.g., vendor-provided API connectors) require security review before registration
  • The tool catalog records provenance: internal tools vs. third-party tools vs. OSS tools

OWASP LLM Top 10

OWASP LLM Risk Tool Registry Applicability Mitigation
LLM01 Prompt Injection Tool descriptions could be crafted to inject instructions into agent context during discovery Registry sanitises tool descriptions on ingestion; description display is rendered as data, not executed
LLM07 Insecure Plugin Design Maliciously defined or poorly validated tools could execute harmful actions Mandatory JSON Schema validation; side_effect_class metadata enables risk-tiered approval; security review for PRIVILEGED tools
LLM08 Excessive Agency An agent with broad tool access could take actions far beyond its intended scope Per-agent capability grants enforce least-privilege; required_capabilities per tool; privileged tools require human-approved grants; audit alerts on unusual access patterns
LLM05 Supply Chain Compromised tool implementation could execute malicious code when invoked Code/image hash verification; isolated sandbox prevents escape; registry-level health monitoring detects behavioural anomalies
LLM04 DoS Agent flood of tool calls could exhaust downstream API quotas Rate limiting per tool_id per agent; health monitor back-pressure; circuit breaker on repeated failures

9. Governance Considerations

Tool Lifecycle Governance

  • Every tool in the registry must have a named owner team; orphaned tools (team disbanded, service retired) are flagged for immediate review
  • Tools with side_effect_class: destructive require dual approval for registration and for any agent capability grant
  • Quarterly tool audit: every tool's usage, health, and access grants are reviewed

Responsible AI

  • Tools that affect individuals (e.g., sending communications, modifying account data) must have their side_effect_class and target_entity_type declared; agents using such tools are subject to higher human oversight requirements
  • Tool descriptions in the registry are part of the AI system's technical documentation under EU AI Act Art. 11

Governance Artefacts

Artefact Owner Frequency Purpose
Tool Capability Register Platform Governance Continuous (auto-generated from catalog) Complete inventory of all tools, their capabilities, access tiers, and owning teams
Tool Invocation Audit Report Platform Engineering Monthly Aggregate tool call volumes, error rates, deprecation usage, access anomalies
Deprecation Impact Report Platform Engineering Per deprecation event Lists agents calling deprecated tool version; migration timeline
Tool Security Review Record Security Engineering At registration of RESTRICTED/PRIVILEGED tools Evidence of security review for supply chain integrity
Quarterly Tool Portfolio Audit Architecture Board Quarterly Review of tool portfolio for redundancy, orphaned tools, access anomalies

10. Operational Considerations

SLOs

SLO Target Window Alert Threshold
Registry API availability 99.99% Monthly < 99.9% triggers P1
Tool discovery latency ≤ 50ms p95 1-hour rolling > 150ms triggers P2
Schema validation latency ≤ 10ms p95 1-hour rolling > 50ms triggers P3
Health probe coverage 100% of registered tools probed within probe interval Per cycle Any skipped probe triggers P3 alert
Audit log availability 99.99% Monthly Any gap is P0

Monitoring

  • Per-tool metrics: call rate, error rate, p50/p95 latency, deprecation usage count
  • Registry-level metrics: discovery query rate, schema validation failure rate, access denied rate (potential probing/attack signal)
  • Alerting: tool error rate spike > 10% over 5-minute window triggers immediate alert to tool owner

Incident Response

Incident Detection Response
Tool health drops to 0% (completely down) Health Monitor immediate alert Mark tool as unavailable; discovery engine returns alternatives; alert tool owner; update status page
Unexpected spike in access denied events Access Control metrics Investigate agent identity attempting denied access; review if capability escalation attack
Tool registration of malicious schema Schema validation / security review Reject registration; alert security team; investigate submitter identity

11. Cost Considerations

Cost Drivers

Cost Driver Scaling Behaviour Control Lever
Registry API compute Linear with query + invocation volume Horizontal scaling; caching of tool definitions in agent memory (TTL refresh)
Schema validation compute Linear with invocations; CPU-bound Pre-compiled schemas; run in-process in dispatcher to avoid network hop
Health probe API calls Linear with registered tools × probe frequency Adjust probe interval by tool criticality; synthetic vs. passive health
Audit log storage Accumulates with invocation volume over retention period Compression; tiered storage; summary aggregation for operational logs
Tool catalog DB Low — read-heavy with infrequent writes Read replica + Redis cache for hot tool definitions

Indicative Cost Range (USD, per month at 1M tool invocations/day)

Component Estimated Monthly Cost Notes
Registry API hosting (cloud container) $200–600 Depends on instance size and HA config
Tool catalog DB (managed PostgreSQL) $100–400 Small instance; read-heavy
Redis cache (managed) $50–200 Hot tool definition cache
Health probe API calls $20–100 Depends on downstream API cost per probe
Audit log storage (90-day operational, 7-year archive) $300–1,000/year Compressed; tiered S3/Blob

12. Trade-Off Analysis

Registry Architecture Options

Option Description Pros Cons Best For
A: Centralised Service Registry (Recommended) Single registry service shared by all agents Single governance point; full portfolio visibility; health monitoring Registry is a dependency; availability SLA required Enterprises with ≥5 agents and governance requirements
B: Agent-Framework Native Tool Store Use LangChain/Semantic Kernel built-in tool store Fastest to implement; no new service Per-agent; no cross-agent sharing; governance is per-framework instance Small teams; PoC; single framework shops
C: Distributed Sidecar Registry Registry logic deployed as a sidecar to each agent No central SPoF; low latency Governance fragmentation; health data is per-sidecar; hard to produce aggregate audit High-availability distributed architectures
D: Service Mesh + API Gateway as Registry Use existing API gateway policies as the tool governance layer Reuses existing infra investment; familiar ops tooling Not AI-tool-native; missing capability discovery, JSON Schema validation, LLM-specific metadata Organisations with mature API gateway investment

Architectural Tensions

Tension Left Pole Right Pole Balance
Central control vs. Developer velocity Registry gates every tool; all tools require approval cycle Agent teams self-register tools with no governance review Two-tier model: PUBLIC tools are self-registered with automatic schema validation; PRIVILEGED tools require governance approval
Strict versioning vs. Agility Every contract change requires a new registered version Schema is flexible; agents adapt dynamically Semantic versioning with backward-compatibility detection; breaking changes always create a new version
Health monitoring depth vs. Cost Probe every tool every 10 seconds for maximum freshness Probe once per hour to minimise API costs Criticality-tiered probe intervals: PRIVILEGED/RESTRICTED tools probed every 60s; PUBLIC tools every 10 min

13. Failure Modes

Failure Mode Likelihood Impact Detection Recovery
Registry API unavailable Low Critical — all agents cannot discover or validate tools Health check; agent startup failure Hot standby; cached tool definitions in agent runtime (TTL-based fallback)
Stale cached tool definition causes schema mismatch Medium Medium — invocation fails; agent retries Schema validation error Cache invalidation on tool update; TTL enforcement
Health probe false positive marks tool as down Medium Medium — agents route to suboptimal alternative Health monitor alert; tool owner callback Manual override API to reset health score; investigate probe logic
Access control bypass via tool ID spoofing Low Critical — unauthorised tool access Access control check validates tool_id against catalog; anomaly detection Immediate audit; agent suspension; investigation
Mass tool deprecation migration failure Low High — agents break when deprecated tool retired Deprecation impact report; migration tracking Extend deprecation period; runbook for emergency agent patching

14. Regulatory Considerations

APRA CPS 234

  • The tool audit log is an information asset log under CPS 234; immutability and integrity controls required
  • Tool access control matrix must be producible on demand for audit purposes

EU AI Act

  • Art. 9 (Risk Management): the tool access tier and side_effect_class metadata support risk-tiered controls
  • Art. 14 (Human Oversight): PRIVILEGED tool capability grants requiring human approval implement Art. 14's human oversight requirement for high-risk actions

ISO 42001

  • §8.4: The tool registry is part of the AI system's operational infrastructure and must be documented in the AI system lifecycle records

NIST AI RMF

  • GOVERN 1.6: The tool capability register and quarterly portfolio audit map to AI risk governance documentation requirements
  • MANAGE 2.4: Tool health monitoring and deprecation management implement active risk management for AI system components

15. Reference Implementations

AWS

Component Service
Registry API Amazon ECS (Fargate) or Lambda; API Gateway
Tool Catalog Amazon RDS PostgreSQL
Discovery Engine Amazon OpenSearch Service
Health Monitor Amazon CloudWatch Synthetics
Audit Log AWS CloudTrail + S3 Object Lock
Access Control AWS IAM + Lambda authoriser

Azure

Component Service
Registry API Azure Container Apps; Azure API Management
Tool Catalog Azure Database for PostgreSQL Flexible Server
Discovery Engine Azure AI Search (semantic search over tool descriptions)
Health Monitor Azure Monitor + Application Insights availability tests
Audit Log Azure Monitor Logs + Immutable Blob Storage

GCP

Component Service
Registry API Cloud Run
Tool Catalog Cloud SQL (PostgreSQL)
Discovery Engine Vertex AI Matching Engine or Cloud Search
Health Monitor Cloud Monitoring Uptime Checks
Audit Log Cloud Audit Logs + Cloud Storage (WORM)

On-Premises

Component Technology
Registry API FastAPI on Kubernetes
Tool Catalog PostgreSQL on Kubernetes
Discovery Engine Elasticsearch or pgvector
Health Monitor Blackbox Exporter (Prometheus)
Audit Log Apache Kafka + Apache Iceberg on MinIO

Pattern ID Relationship Type Notes
Single Agent Pattern EAAPL-AGT001 Depends On Every agent's Tool Dispatcher relies on the registry
Agent Sandboxing EAAPL-AGT004 Integrates With Registry provides sandbox_requirements per tool to the executor
Agent Identity and Authorisation EAAPL-AGT009 Depends On Access control checks validate agent capability grants from the identity store
Agent Cost Governance EAAPL-AGT010 Integrates With Tool invocation cost metadata is sourced from the registry
Multi-Agent Orchestration EAAPL-MAG001 Extends Orchestrators use the registry to assign tools to worker agents

17. Maturity Assessment

Overall Maturity: Proven

Dimension Score (1–5) Evidence
Adoption Breadth 4 AWS Bedrock Agents, Azure AI Foundry, and major agent frameworks implement registries
Tooling Ecosystem 4 MCP (Model Context Protocol), OpenAI function calling schema, LangChain tool specs all serve as tool definition standards
Governance Tooling 3 Custom governance layer (lifecycle, deprecation) typically requires bespoke development
Security Hardening 4 JSON Schema validation and RBAC well understood; supply chain for tools still maturing
Operational Patterns 4 Health monitoring and deprecation patterns well-established from API gateway heritage

18. Revision History

Version Date Author Changes
1.0 2024-05-01 Architecture Board Initial publication
1.1 2024-09-01 Security Engineering Added OWASP LLM07 and LLM08 mitigations; supply chain hash verification
1.2 2024-12-01 Platform Engineering Added health monitor architecture; capability-based discovery section
1.3 2025-03-10 Architecture Board Added MCP reference; EU AI Act Art. 14 mapping; deprecation lifecycle detail
← Back to LibraryMore Agentic AI