Tool Governance

Tool Registry

All tools are defined in src/tools/registry.ts in the AI Service. This is the single source of truth for tool availability and permissions.

Current Tools

Caution

The four tools below are the governance CATEGORIES, not the registry. src/tools/registry.ts ships roughly forty executors — the search family, traces and exceptions, anomaly detection, alerting, cluster and index tools, OTEL logs, the compliance and warden families, platform data, and the backend scan/project tools. GET /api/v1/trajectory/tool-schemas serves the live list with each tool’s description and parameter schema; that endpoint is the current answer to “which tools exist”, and this page is a summary of how they are gated.

Tool	Category	Permission	Description
semantic_search	read_only	basic	Natural language log search via k-NN
opensearch_query	read_only	standard	OpenSearch queries and aggregations
get_scan_results	read_only	standard	Compliance scan result retrieval
analyze_logs	read_only	standard	AI-powered log analysis via Analyzer

Tool Categories

read_only — Safe for all agents

Tools that only read data. No side effects. These can be granted to any agent type.

write — Restricted (Phase 3)

Tools that create or modify data:

• create_scan — Trigger a new compliance scan
• update_agent_config — Modify agent settings
• dismiss_anomaly — Mark an anomaly as acknowledged

external — Requires explicit approval (Phase 3)

Tools that call external services:

• send_discord_alert — Post to Discord
• send_email — Email notification
• call_webhook — Custom webhook

admin — Platform-only, never agent-accessible

Tools reserved for system operations, never exposed to user-created agents.

Permission Levels

Level	Description	Who Can Use
basic	Minimal risk, broad access	All agent types
standard	Normal operations	User-created + system agents
elevated	Sensitive operations	Admins only
admin	Platform administration	System processes only

Per-Agent Tool Filtering

The AgentLoop accepts a toolsAllowed array to restrict which tools an agent can call:

// Full access (interactive chat)
const loop = new AgentLoop(allTools);

// Agent-restricted access
const loop = new AgentLoop(allTools, {
  toolsAllowed: ["semantic_search", "opensearch_query"]
});
// Agent can ONLY call these two tools, even if it tries to call others

The filter happens before tool definitions are sent to the LLM, so the model never sees tools it cannot use.

Tool Browser UI

The Tool Browser modal allows users to explore tools when building agents:

┌──────────────────────────────────────────────────┐
│ Tool Browser                                     │
├────────────────┬─────────────────────────────────┤
│ read_only      │ semantic_search                 │
│   semantic_search │ Permission: basic            │
│   opensearch_query│                              │
│   get_scan_results│ Search logs using natural    │
│   analyze_logs │ language. Uses k-NN vector      │
│                │ similarity to find semantically  │
│ write (Phase 3)│ similar log entries.            │
│   [locked]     │                                 │
│                │ Input schema:                   │
│ external       │ • query: string (required)      │
│   [locked]     │ • index: string (optional)      │
│                │ • k: number (default: 10)       │
└────────────────┴─────────────────────────────────┘

Adding New Tools

To add a new tool to the registry:

1. Create src/tools/myNewTool.tool.ts in the AI Service
2. Register in src/tools/registry.ts:

my_new_tool: {
  category: 'read_only',
  permissionLevel: 'standard',
  description: 'What this tool does',
  inputSchema: { ... },
  handler: myNewToolHandler
}

3. Update tool documentation in this playbook
4. The tool is immediately available for agents that include it in toolsAllowed

Tool Usage Analytics (Phase 3)

Planned: Track which tools are used most by agents, flag tools with high error rates, and surface usage stats in the Tool Browser.