PRIVATE.ME ACI #207

AI agents can't discover tools by capability

Decentralized tool discovery registry with capability-based search, trust verification, and automatic routing. No hardcoded service catalogs.

TypeScript 5.x Node.js 20+ Web Crypto API xLink Integration

The Problem

Hardcoded Tool Names, No Trust Levels, No Schema Validation

AI agents rely on hardcoded service catalogs to invoke external tools. Tool names are static strings, trust levels are undefined, and schema mismatches cause runtime failures.

Discovery Failure

Agent can't find tools by what they do

Tool names are opaque identifiers. No way to search for "payment processing" and discover available implementations.

Capability Gap

Trust Unknown

No distinction between verified and experimental tools

Agents have no trust signal. Verified production tools mixed with untested experimental implementations.

Security Risk

Schema Mismatch

Runtime failures from invalid inputs

No schema validation at discovery time. Type mismatches, missing required fields cause invocation failures.

Reliability Issue

Static Catalogs

Hardcoded service lists don't scale

Every new tool requires code changes across all agents. No dynamic discovery, no decentralization.

Scalability Blocker

How It Works

Tool Registry with Capability Search, Trust Levels, Discovery

xRegistry provides a decentralized discovery system where agents register tool schemas with capabilities and trust levels. Other agents search by capability, filter by trust, and auto-discover compatible tools.

import { ToolRegistry } from '@private.me/xregistry';

const registry = new ToolRegistry();

// Register tool with schema, capabilities, trust level
const result = await registry.register({
  name: 'stripe:createCharge',
  description: 'Create a payment charge',
  schema: {
    type: 'object',
    properties: {
      amount: { type: 'number' },
      currency: { type: 'string' }
    },
    required: ['amount', 'currency']
  },
  trustLevel: 'verified',
  endpoint: 'https://api.stripe.com/v1/charges',
  capabilities: ['payment', 'charge', 'stripe'],
  owner: 'did:key:z6Mk...',
  version: '1.0.0'
});

Discover Tools by Capability

import { discover } from '@private.me/xregistry';

// Search for payment tools, filter by trust level
const result = discover('payment', registry, {
  minTrustLevel: 'verified',
  limit: 5
});

if (result.primary) {
  console.log('Primary match:', result.primary.name);
  console.log('Endpoint:', result.primary.endpoint);
  console.log('Schema:', result.primary.schema);
}

xLink Integration

When integrated with xLink's agent.call(), xRegistry enables automatic tool resolution. Agents can call tools by capability name, and xRegistry discovers compatible implementations, ranks by trust level, and routes invocations automatically.

See It In Action

Service Discovery & Registration

$ registry.register(toolSchema)

      → Registering: stripe:createCharge
    
      → Capabilities: [payment, charge, stripe]
    
      → Trust Level: verified
    
      ✓ Tool registered successfully

Capability-Based Discovery

stripe:createCharge

VERIFIED • payment, charge

Create a payment charge with Stripe API

paypal:processPayment

COMMUNITY • payment, paypal

Process payments through PayPal

custom:billCustomer

EXPERIMENTAL • payment, billing

Custom billing implementation

Features

Trust-Based Classification, Schema Validation, Auto-Discovery

Trust Levels

Three-tier trust classification guides agent decision-making:

Trust Level	Verification	Use Case
verified	Cryptographically verified by registry authority	Production use, critical operations
community	Community-attested via peer review	General use, non-critical operations
experimental	Self-registered, no verification	Development, testing only

Capability-Based Search

Tools register with capability tags describing what they do. Agents search by natural language capability queries, not hardcoded tool names.

Search Examples

// Find all payment processing tools
const paymentTools = registry.search('payment processing');

// Filter by trust level
const verified = registry.listByTrustLevel('verified');

// Get specific tool
const stripe = registry.get('stripe:createCharge');

Schema Validation

Every tool registers with a JSON Schema describing inputs and outputs. Agents validate arguments at discovery time, preventing runtime type mismatches.

Automatic Routing

When integrated with xLink, registry enables zero-config tool resolution. Agents call by capability, registry discovers implementations, xLink routes invocations.

Quick Start

Register, Search, Discover

Install

pnpm add @private.me/xregistry

Basic Usage

import { ToolRegistry } from '@private.me/xregistry';

const registry = new ToolRegistry();

// Register a tool
await registry.register({
  name: 'json-transformer',
  description: 'Transform JSON data structures',
  schema: {
    type: 'object',
    properties: {
      data: { type: 'object' },
      template: { type: 'object' }
    },
    required: ['data', 'template']
  },
  trustLevel: 'community',
  endpoint: 'did:xail:transformer-service',
  capabilities: ['data-transform', 'json'],
  owner: 'did:key:z6Mk...',
  version: '1.0.0'
});

// Search by capability
const tools = registry.search('json transform');
console.log(`Found ${tools.length} tools`);

API Reference

ToolRegistry Class & Discovery Functions

Registry Operations

new ToolRegistry()

Create a new decentralized tool registry instance.

registry.register(tool: ToolMetadata): Promise<Result<void, RegistryError>>

Register a tool with schema, capabilities, and trust level. Returns error if tool name already exists or schema is invalid.

registry.search(query: string): readonly ToolMetadata[]

Search tools by keyword (matches capabilities, name, description). Returns all matching tools.

registry.listByTrustLevel(level: TrustLevel): readonly ToolMetadata[]

Filter tools by trust level. Returns all tools with specified trust level.

registry.get(toolName: string): ToolMetadata | undefined

Retrieve specific tool registration by exact name. Returns undefined if not found.

registry.unregister(toolName: string): Promise<Result<void, RegistryError>>

Remove a tool from the registry. Returns error if tool not found.

Discovery Functions

discover(capability: string, registry: ToolRegistry, options?): DiscoveryResult

Search by capability with trust ranking. Returns primary match, all matches, and alternatives. Options: minTrustLevel, limit, includeAlternatives.

resolveToolEndpoint(toolAlias: string, registry: ToolRegistry): Result<ToolMetadata, DiscoveryError>

Resolve exact tool name to metadata. Returns Result with tool metadata or error if not found.

autoDiscover(nameOrCapability: string, registry: ToolRegistry, options?): Result<DiscoveryResult, DiscoveryError>

Try exact match first, fallback to capability search. Returns Result with discovery result or error.

xLink Integration

Automatic Tool Discovery with agent.call()

Integrate xRegistry with xLink's agent communication layer for zero-config tool resolution.

Enable Registry for xLink

import { setToolRegistry, call } from '@private.me/xlink';
import { ToolRegistry } from '@private.me/xregistry';

const registry = new ToolRegistry();

// Register tools
await registry.register({
  name: 'stripe:createCharge',
  capabilities: ['payment', 'charge'],
  trustLevel: 'verified',
  /* ... */
});

// Enable registry for agent.call()
setToolRegistry(registry);

// Now agent.call() auto-discovers tools
const result = await call('payment', {
  amount: 100,
  currency: 'usd'
});

Integration Benefits

Zero-config resolution: No hardcoded endpoints
Trust ranking: Verified tools preferred automatically
Capability search: Find tools by what they do
Graceful degradation: Falls back to original alias if discovery fails
Alternative suggestions: Shows other options via progress callback

GET STARTED

Free for All Developers

xRegistry is a free developer tool. No credit card required, no trial period, no subscription. Install and start discovering tools immediately.

OPEN TO ALL

xRegistry is part of the Private.Me platform's commitment to developer tools. Use it in personal projects, commercial applications, or enterprise environments without cost.

pnpm add @private.me/xregistry

For custom deployments or enterprise support, contact contact@private.me.