Hardcoded tool catalogs break when your agent needs to choose between 200 MCP servers instead of five. AWS Agent Registry solves this by moving tool discovery from build time to runtime. Instead of compiling every available tool into your orchestrator, agents query a semantic registry to find the right MCP server or A2A agent when they need it.
The pattern is a three-step loop: Discover (semantic search over tool descriptions), Instantiate (spin up the selected MCP server), Execute (invoke the tool). This shifts the wiring problem from static configuration to dynamic lookup.
The Scaling Problem with Static Tool Catalogs
When you hardcode tool registration, every new MCP server requires a code change and redeployment. At five tools, this is manageable. At 50, it becomes a bottleneck. At 500, it’s unworkable.
Static catalogs also force agents to load metadata for every tool at startup, even if they only use three during a session. This bloats memory and slows initialization.
The bigger issue is tool selection. If you have three different weather APIs, two payment processors, and four database connectors, the orchestrator needs logic to pick the right one. Hardcoding that logic creates brittle if-then chains that break when tools change.
How the Discover-Instantiate-Execute Loop Works
AWS Agent Registry implements a query-driven discovery flow:
- Discover: The orchestrator receives a user request and generates a semantic query describing the needed capability (e.g., “retrieve current weather data for a location”).
- Semantic Search: The registry performs vector similarity search over tool descriptions to find matching MCP servers or A2A agents.
- Instantiate: The orchestrator spins up the selected MCP server (if not already running) and establishes a connection.
- Execute: The orchestrator invokes the tool, receives results, and continues the agent workflow.
The registry stores tool metadata: name, description, input schema, output schema, endpoint configuration, and versioning information. Descriptions are embedded into vectors for semantic search.
Registry Schema and Tool Metadata
Each tool entry in the registry contains:
- Tool identifier: Unique name or URI
- Description: Natural language explanation of what the tool does
- Input schema: JSON Schema defining required and optional parameters
- Output schema: Expected response structure
- Endpoint: Connection details (URL, protocol, authentication requirements)
- Version: Semantic version or commit hash
- Tags: Categorical metadata for filtering (domain, compliance level, cost tier)
The description field is critical. It needs enough detail for semantic search to distinguish similar tools but not so much that it dilutes the embedding. A good description includes the tool’s purpose, key parameters, and constraints.
Example:
{
"tool_id": "weather-api-v2",
"description": "Retrieves current weather conditions and 7-day forecast for any global location using latitude/longitude or city name. Returns temperature, humidity, wind speed, and precipitation probability.",
"input_schema": {
"type": "object",
"properties": {
"location": {"type": "string"},
"units": {"type": "string", "enum": ["metric", "imperial"]}
},
"required": ["location"]
},
"endpoint": "https://weather.mcp.example.com",
"version": "2.1.3",
"tags": ["weather", "external-api", "rate-limited"]
}Semantic Search and Tool Selection
The orchestrator converts the agent’s intent into a query embedding and searches the registry for the highest-scoring tools. This works when tool descriptions are distinct. It fails when multiple tools have overlapping descriptions.
To prevent collisions, the registry needs disambiguation logic:
- Contextual filtering: Use tags or metadata to narrow the search space before semantic matching (e.g., only search tools tagged “payment” if the agent is processing a transaction).
- Ranking signals: Combine semantic similarity with usage frequency, latency history, or cost metrics.
- Fallback prompts: If the top two tools score within a threshold, ask the LLM to choose based on additional context.
The latency penalty for runtime discovery depends on your embedding model and index size. A vector search over 500 tools typically adds 20-100ms. If your agent workflow already includes multiple LLM calls (each 500-2000ms), this is negligible. If you’re building a low-latency chatbot, it matters.
Caching and Version Management
Re-discovering the same MCP server on every invocation wastes time. The orchestrator should cache:
- Tool metadata: Store the full schema locally after the first discovery.
- Connection handles: Keep MCP server connections alive between invocations if the tool is used frequently.
- Embeddings: Pre-compute and cache query embeddings for common intents.
Version drift is a real problem. If a tool’s behavior changes but its registry description doesn’t, the agent will invoke it expecting old behavior. Solutions:
- Schema validation: Compare the cached schema to the live schema on each invocation. If they differ, invalidate the cache and re-discover.
- Heartbeat checks: Periodically ping registered tools to verify they’re still available and haven’t changed.
- Semantic versioning: Require tools to increment version numbers when input/output schemas change.
Failure Modes and Observability
Runtime discovery introduces new failure points:
| Failure Mode | Symptom | Mitigation |
|---|---|---|
| Registry unavailable | Agent can’t discover any tools | Cache last-known tool list; fall back to static catalog |
| Semantic search returns wrong tool | Agent invokes incorrect MCP server | Log tool selection reasoning; add human-in-the-loop for high-risk actions |
| Tool schema drift | Tool rejects invocation due to schema mismatch | Validate schemas before invocation; retry with re-discovery |
| MCP server unreachable | Instantiation fails | Implement retry with exponential backoff; mark tool as unavailable |
| Slow discovery | High latency on first invocation | Pre-warm cache with frequently used tools |
Observability requirements:
- Log every discovery query: Capture the intent, top-N results, and selected tool.
- Trace tool invocations: Link discovery, instantiation, and execution spans.
- Monitor cache hit rates: Low hit rates indicate poor caching strategy or high tool churn.
- Alert on schema mismatches: Track how often cached schemas fail validation.
Deployment Shape
AWS Agent Registry is not a standalone service. It’s a pattern you implement using:
- Vector database: Store tool embeddings (Pinecone, Weaviate, OpenSearch with k-NN).
- Metadata store: Store tool schemas and endpoint configuration (DynamoDB, RDS).
- Orchestrator: Agent runtime that queries the registry and invokes tools (Step Functions, custom Lambda, Bedrock Agents).
A minimal deployment:
- Ingest tools: Extract metadata from MCP servers and A2A agents, generate embeddings, write to vector DB.
- Query endpoint: Expose an API that accepts natural language queries and returns ranked tool matches.
- Orchestrator integration: Modify your agent runtime to call the query endpoint before tool invocation.
The registry can be centralized (one registry for all agents) or federated (each team maintains a registry for their domain). Centralized registries simplify discovery but create a single point of failure. Federated registries reduce blast radius but require cross-registry search.
When to Use Runtime Discovery
Runtime discovery makes sense when:
- You have more than 20 tools and the catalog is growing.
- Tools are added or updated frequently (weekly or faster).
- Multiple teams contribute tools and you can’t coordinate static registration.
- Agents need to adapt to changing tool availability (e.g., a payment processor goes down, fall back to an alternative).
Skip runtime discovery if:
- You have fewer than 10 tools and they rarely change.
- Latency is critical and you can’t afford the discovery overhead.
- Your tools are tightly coupled to the orchestrator and don’t benefit from dynamic wiring.
- You lack the infrastructure to run a vector database and maintain embeddings.
Technical Verdict
AWS Agent Registry is infrastructure for scaling agent tool catalogs. It replaces hardcoded tool lists with semantic search, enabling agents to discover and invoke MCP servers at runtime. The pattern works when you have dozens or hundreds of tools, frequent tool updates, or multiple teams contributing capabilities.
The trade-off is complexity. You need a vector database, an embedding pipeline, schema validation, and cache invalidation logic. For small agent systems (under 20 tools), static catalogs are simpler and faster.
The biggest risk is semantic search returning the wrong tool. Invest in good tool descriptions, contextual filtering, and logging. If your agent makes high-stakes decisions (financial transactions, infrastructure changes), add human approval before executing discovered tools.
Use this pattern when your tool catalog outgrows static configuration. Skip it if you’re building a proof-of-concept or your tool set is stable.