What can you do with this server?

This server is an encrypted LLM gateway and MCP server that routes generation through OpenAI-compatible, CLI, and local LLM providers while managing credentials, tools, and observability. * Generate text via /v1/generate, /v1/chat/completions, or MCP llm_generate, with provider/model routing, fallback, project-scoped credentials, and three-part prompts. * Store, list, and delete encrypted API keys and auth files per provider/project. * List providers, models, latency, cost estimates, usage, and Prometheus metrics. * Manage provider groups for load balancing, failover, and session stickiness. * Search codebases semantically using keyword, vector, or hybrid search, with optional import following. * Maintain shared CRDT state (counters, registers, sets) for multi-agent collaboration. * Configure circuit breakers and inspect provider health/failure stats. * Use approval workflows to gate destructive MCP tools. * Generate with local LLMs (Ollama/LM Studio) and discover/enrich local models with HuggingFace metadata. * Paginate, navigate, search, and check compaction needs for long conversations.

Which integrations are available for this server?

Supports GitHub Copilot's API through token-based credentials, allowing code generation and model access.

How do I use mcp-llm-bridge?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-llm-bridge generate a short explanation of machine learning" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-llm-bridge

by JNZader

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

MCP LLM Bridge

Encrypted LLM gateway and MCP server for routing API keys, CLI subscriptions, and model selection through one OpenAI-compatible endpoint.

License: MIT Node.js 22+ TypeScript Docker Ready

Read this in: English · Español

Demo Links

Live gateway: https://gateway.javierzader.com
GHAGGA integration target: https://github.com/JNZader/ghagga
OpenCode: https://github.com/anomalyco/opencode

Visuals coming soon.

Related MCP server: MCP-AI-Gateway

Quick Portfolio Snapshot

One service for LLM routing, encrypted credential storage, MCP tooling, and OpenAI-compatible HTTP access.
11 provider adapters today: 5 direct API providers plus 6 CLI-backed providers.
Supports API keys and auth-file workflows, including auth.json and .credentials.json.
Includes task-aware bridge routing, model routing, project-scoped credentials with global fallback, semantic code search, context compression, and CRDT shared state.
Ships as a local dev tool, self-hosted HTTP gateway, MCP stdio server, and Docker deployment.

Why It Matters

Centralizes secrets instead of scattering provider tokens across every project and tool.
Lets you reuse CLI subscriptions such as OpenCode, Claude, Gemini, Codex, Qwen, and Copilot behind one interface.
Gives OpenAI-compatible tools a single stable endpoint while preserving provider/model resolution metadata.
Supports multi-project setups where project-specific credentials override _global defaults cleanly.
Exposes MCP tools beyond plain generation: vault operations, code search, shared state, usage inspection, and provider-group management.

Quick Start

pnpm install
pnpm run serve

Open http://localhost:3456.

Store a credential and generate text:

curl -X POST http://localhost:3456/v1/credentials \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic","apiKey":"sk-ant-..."}'

curl -X POST http://localhost:3456/v1/generate \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Explain quicksort in one paragraph"}'

If you set LLM_GATEWAY_AUTH_TOKEN, add Authorization: Bearer <token> to every protected route.

Jump to Technical Docs

Full API reference: Technical README
Auth and credential model: Authentication, Credential Management
MCP integration: MCP Server
Docker and self-hosting: Docker Deployment

Technical README

Quick Start

# Install dependencies
pnpm install

# Start the HTTP server + dashboard
pnpm run serve

# MCP stdio mode only
pnpm run start

Basic HTTP flow:

# Store a global Anthropic key
curl -X POST http://localhost:3456/v1/credentials \
  -H 'Content-Type: application/json' \
  -d '{"provider":"anthropic","apiKey":"sk-ant-..."}'

# Generate text with automatic provider selection
curl -X POST http://localhost:3456/v1/generate \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"Explain quicksort in one paragraph"}'

If auth is enabled:

curl -X POST http://localhost:3456/v1/generate \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"prompt":"Explain quicksort in one paragraph"}'

Dashboard

The repo currently has two dashboard surfaces:

Local inline shell at http://localhost:3456/ — legacy local ops surface served directly by the bridge. This remains the source of truth for local credential/auth-file management and quick test generation.
React admin app under dashboard/ (built into docs/) — admin/observability surface for overview, providers, usage, groups, circuit breakers, settings, and related views.

They intentionally coexist for now and do not have full feature parity.

Hosted demo: https://gateway.javierzader.com
Local inline shell: http://localhost:3456

First-Time Setup

Start the gateway with pnpm run serve.
Open the dashboard.
Enter the base URL for your gateway.
Enter the bearer token if LLM_GATEWAY_AUTH_TOKEN is configured.
Test the connection and save.

Local Inline Shell Capabilities

Add, list, filter, and delete encrypted API keys.
Upload auth files for CLI-backed providers.
Inspect provider availability and available models.
Send test prompts and inspect returned provider/model metadata.
Work with project-scoped credentials without exposing raw secrets.

React Admin App Capabilities

Overview / provider status / usage / groups / circuit breakers / settings
Admin-facing operational visibility over bridge subsystems
Hosted separately from the inline shell via the dashboard/ app

Recommended auth-file mappings in the UI and API:

opencode -> auth.json
claude -> .credentials.json
codex -> auth.json
gemini -> settings.json and oauth_creds.json
qwen -> settings.json and oauth_creds.json
copilot -> use token credentials instead of auth files

API Reference

All protected endpoints require:

Authorization: Bearer <your-token>

When LLM_GATEWAY_AUTH_TOKEN is not set, auth is disabled for local development. GET /health always stays public.

Core HTTP Endpoints

Endpoint	Method	Description
`/health`	GET	Public health check for uptime monitors and platforms like Coolify
`/metrics`	GET	Prometheus metrics export
`/v1/generate`	POST	Native generation endpoint
`/v1/chat/completions`	POST	OpenAI-compatible chat completions
`/v1/models`	GET	OpenAI-compatible model list
`/v1/providers`	GET	Provider availability and metadata
`/v1/latency`	GET	Current latency measurements when latency routing is enabled
`/v1/cost/estimate`	GET	Cost estimate for a model and token counts
`/v1/cost/models`	GET	Model pricing table
`/v1/usage`	GET	Raw usage records
`/v1/usage/summary`	GET	Aggregated usage summary
`/v1/credentials`	POST / GET	Store and list encrypted API keys
`/v1/credentials/:id`	DELETE	Delete a stored credential
`/v1/files`	POST / GET	Store and list encrypted auth files
`/v1/files/:id`	DELETE	Delete a stored auth file
`/v1/groups`	GET / POST	List or create provider groups
`/v1/groups/:id`	PUT / DELETE	Update or delete a provider group

`POST /v1/generate`

Native generation endpoint with provider/model selection and project-scoped credential resolution.

# Auto-select provider
curl -X POST http://localhost:3456/v1/generate \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"prompt":"Explain quicksort in one paragraph"}'

# Explicit provider + model + project
curl -X POST http://localhost:3456/v1/generate \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'X-Project: my-app' \
  -d '{
    "prompt":"Write a haiku about Rust",
    "provider":"groq",
    "model":"llama-3.3-70b-versatile",
    "maxTokens":256,
    "system":"You are a poet.",
    "project":"my-app"
  }'

Request body:

Field	Type	Required	Description
`prompt`	string	Yes	User prompt
`system`	string	No	System prompt
`provider`	string	No	Preferred provider ID
`model`	string	No	Specific model ID
`maxTokens`	number	No	Max output tokens
`project`	string	No	Credential scope
`strict`	boolean	No	Strict routing behavior when supported

Response:

{
  "text": "Quicksort is a divide-and-conquer...",
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "tokensUsed": 150,
  "requestedProvider": null,
  "requestedModel": null,
  "resolvedProvider": "anthropic",
  "resolvedModel": "claude-sonnet-4-20250514",
  "fallbackUsed": false
}

`POST /v1/chat/completions`

OpenAI-compatible chat endpoint. This is the drop-in path for tools that already speak OpenAI format.

Non-streaming and streaming requests are supported.
System messages are collapsed into the system prompt.
Conversation context is reconstructed from earlier messages.
Response stays OpenAI-compatible and adds x_gateway metadata.

curl -X POST http://localhost:3456/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "model":"claude-sonnet-4-20250514",
    "messages":[
      {"role":"system","content":"You are a helpful assistant."},
      {"role":"user","content":"What is the capital of France?"}
    ],
    "max_tokens":1024
  }'

Response:

{
  "id": "chatcmpl-<uuid>",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "claude-sonnet-4-20250514",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "The capital of France is Paris." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 0, "completion_tokens": 0, "total_tokens": 150 },
  "x_gateway": {
    "requestedProvider": null,
    "requestedModel": "claude-sonnet-4-20250514",
    "resolvedProvider": "anthropic",
    "resolvedModel": "claude-sonnet-4-20250514",
    "fallbackUsed": false,
    "tokensUsed": 150
  }
}

`GET /v1/models`

Lists available models in OpenAI-compatible format.

curl http://localhost:3456/v1/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "object": "list",
  "data": [
    {
      "id": "claude-sonnet-4-20250514",
      "object": "model",
      "created": 0,
      "owned_by": "llm-gateway",
      "name": "Claude Sonnet 4",
      "provider": "anthropic",
      "max_tokens": 8192
    }
  ]
}

`GET /v1/providers`

Lists registered providers and their availability.

curl http://localhost:3456/v1/providers \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "providers": [
    { "id": "anthropic", "name": "Anthropic", "type": "api", "available": true },
    { "id": "openai", "name": "OpenAI", "type": "api", "available": false },
    { "id": "opencode-cli", "name": "OpenCode CLI", "type": "cli", "available": true }
  ]
}

Credentials API

Store API keys encrypted at rest. Upsert key is (provider, keyName, project).

# Global credential
curl -X POST http://localhost:3456/v1/credentials \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "provider":"anthropic",
    "keyName":"default",
    "apiKey":"sk-ant-api03-..."
  }'

# Project-scoped credential
curl -X POST http://localhost:3456/v1/credentials \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "provider":"openai",
    "keyName":"default",
    "apiKey":"sk-proj-...",
    "project":"my-app"
  }'

{ "id": 1, "provider": "anthropic", "keyName": "default", "project": "_global" }

List credentials:

curl http://localhost:3456/v1/credentials \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl 'http://localhost:3456/v1/credentials?project=my-app' \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "credentials": [
    {
      "id": 1,
      "provider": "anthropic",
      "keyName": "default",
      "project": "_global",
      "maskedValue": "sk-ant-...***",
      "createdAt": "2025-01-15 10:30:00",
      "updatedAt": "2025-01-15 10:30:00"
    }
  ]
}

Delete a credential:

curl -X DELETE http://localhost:3456/v1/credentials/1 \
  -H 'Authorization: Bearer YOUR_TOKEN'

Auth Files API

Store auth files for CLI-backed providers encrypted at rest. Upsert key is (provider, fileName, project).

This is the path that preserves the older auth.json and .credentials.json workflows.

# OpenCode auth.json
curl -X POST http://localhost:3456/v1/files \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "provider":"opencode",
    "fileName":"auth.json",
    "content":"{\"token\":\"oc-...\"}",
    "project":"_global"
  }'

# Claude CLI .credentials.json
curl -X POST http://localhost:3456/v1/files \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "provider":"claude",
    "fileName":".credentials.json",
    "content":"{\"claudeAiOauth\":{...}}",
    "project":"my-app"
  }'

{ "id": 1, "provider": "opencode", "fileName": "auth.json", "project": "_global" }

List auth files:

curl http://localhost:3456/v1/files \
  -H 'Authorization: Bearer YOUR_TOKEN'

curl 'http://localhost:3456/v1/files?project=my-app' \
  -H 'Authorization: Bearer YOUR_TOKEN'

{
  "files": [
    {
      "id": 1,
      "provider": "opencode",
      "fileName": "auth.json",
      "project": "_global",
      "createdAt": "2025-01-15"
    }
  ]
}

Delete an auth file:

curl -X DELETE http://localhost:3456/v1/files/1 \
  -H 'Authorization: Bearer YOUR_TOKEN'

Usage, Cost, Metrics, and Health

Usage records:

curl 'http://localhost:3456/v1/usage?project=my-app&limit=50' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Usage summary:

curl 'http://localhost:3456/v1/usage/summary?groupBy=provider&project=my-app' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Cost estimate:

curl 'http://localhost:3456/v1/cost/estimate?model=claude-sonnet-4-20250514&inputTokens=1000&outputTokens=500' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Prometheus metrics:

curl http://localhost:3456/metrics \
  -H 'Authorization: Bearer YOUR_TOKEN'

Health check:

curl http://localhost:3456/health

GET /health returns the runtime VERSION constant (src/core/constants.ts) plus uptime, auth mode, and provider counts:

{
  "status": "ok",
  "version": "0.3.1",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "uptime": 3600,
  "auth": { "enabled": true, "mode": "bearer" },
  "providers": { "total": 11, "available": 3 }
}

Note: the VERSION constant and the version field in package.json are not kept in lockstep — /health reports the former.

Provider Groups

Provider groups let you define logical pools for balancing and failover.

curl -X POST http://localhost:3456/v1/groups \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "name":"fast-models",
    "modelPattern":"gpt-*,claude-*",
    "members":[
      {"provider":"groq","weight":2,"priority":1},
      {"provider":"anthropic","weight":1,"priority":2}
    ],
    "strategy":"weighted",
    "stickyTTL":300
  }'

Providers

API Providers

Provider	ID	Auth	Example Models
Anthropic	`anthropic`	API key	`claude-sonnet-4-20250514`, `claude-haiku-4-20250414`
OpenAI	`openai`	API key	`gpt-4o`, `gpt-4o-mini`, `o3-mini`
Google	`google`	API key	`gemini-2.5-flash`, `gemini-2.5-pro`
Groq	`groq`	API key	`llama-3.3-70b-versatile`, `llama-3.1-8b-instant`
OpenRouter	`openrouter`	API key	`deepseek/deepseek-chat`, `anthropic/claude-sonnet-4`

CLI Providers

Provider	ID	Auth Material	Notes
OpenCode CLI	`opencode-cli`	`auth.json` from vault	Large model catalog via subscription routing
Claude CLI	`claude-cli`	`.credentials.json` from vault	Uses Claude Max credentials
Gemini CLI	`gemini-cli`	CLI auth files	Local CLI-backed execution
Codex CLI	`codex-cli`	`auth.json`	OpenAI CLI-backed execution
Qwen CLI	`qwen-cli`	CLI auth files	Qwen local/subscription access
Copilot CLI	`copilot-cli`	token credentials	GitHub Copilot-backed routing

OpenCode Model Coverage

OpenCode is the biggest catalog here and is one reason this bridge is useful.

GET /v1/models refreshes from opencode models (TTL 5 min). The adapter fallback is the opencode/* free tier plus opencode-go/* subscription ids; discovery adds whatever else the CLI lists (google/*, antigravity/*, openai/*, kimi-for-coding/*). Anthropic and GitHub Copilot ids are not advertised unless the CLI lists them.

Representative examples:

opencode-go/deepseek-v4-flash
opencode/big-pickle
opencode-go/kimi-k2.7-code
openai/gpt-5.4

Provider Priority and Fallback

Default behavior without an explicit provider/model:

API providers are tried first.
CLI providers follow as fallback.
If a model is explicitly requested, the owning provider is preferred.
If bridge routing is enabled, the bridge can override the initial provider choice and then walk the configured fallback chain.

Authentication

Bearer Token

Set LLM_GATEWAY_AUTH_TOKEN to protect HTTP routes.

# Generate a secure token
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

export LLM_GATEWAY_AUTH_TOKEN="your-64-char-hex-token"

The token must be at least 32 characters.

Auth Rules

Path	Bearer Auth Required
`GET /health`	No
`OPTIONS *` (CORS preflight)	No
`/auth/github/*`	No
`/v1/admin/*` (entire admin surface)	No
All other HTTP routes, including dashboard and `/metrics`, when token is set	Yes

Important behavior:

The bearer-auth middleware skips the entire /v1/admin/* prefix, not just /v1/admin/auth-config. Admin routes gate themselves with their own dashboard/GitHub-OAuth JWT checks (verifyDashboardJwt) rather than the static bearer token. Keep this in mind when exposing the gateway publicly.
The dashboard (non-admin routes) is protected when bearer auth is enabled.
MCP stdio does not use HTTP bearer auth because it runs as a local process.
Token comparison is constant-time via timingSafeEqual.

Project Scoping

Project scope can be supplied in either place:

JSON body field: "project": "my-app"
Header: X-Project: my-app

Body field wins over header.

Credential Management

Global vs Project Credentials

Credential resolution follows the same pattern for API keys and auth files:

Try the project-specific entry.
Fall back to _global.

That lets you keep a shared default while still isolating overrides per app or customer.

API Keys

API keys are encrypted with AES-256-GCM and stored in SQLite.

# Global key
curl -X POST http://localhost:3456/v1/credentials \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"provider":"anthropic","apiKey":"sk-ant-..."}'

# Project key
curl -X POST http://localhost:3456/v1/credentials \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"provider":"anthropic","apiKey":"sk-ant-project-...","project":"my-app"}'

Auth Files

CLI adapters use file-based auth where necessary. These files are also encrypted and stored in the vault.

# OpenCode auth.json
curl -X POST http://localhost:3456/v1/files \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "provider":"opencode",
    "fileName":"auth.json",
    "content":"{\"token\":\"oc-...\"}"
  }'

# Claude CLI .credentials.json
curl -X POST http://localhost:3456/v1/files \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "provider":"claude",
    "fileName":".credentials.json",
    "content":"{\"claudeAiOauth\":{...}}"
  }'

Claude and OpenCode Credential Sync Pattern

The vault layer also contains a Claude OAuth integration that:

Reads ~/.claude/.credentials.json
Refreshes the token when needed
Syncs the token into OpenCode-style auth.json

That matters because this bridge can unify Claude CLI and OpenCode auth flows instead of treating them as separate credential silos.

Cross-Model Bridge

The bridge is an optional routing layer driven by ~/.llm-gateway/bridge.yaml.

Flow:

Classify the prompt into a task type.
Resolve a preferred provider from routes.
Try that provider first.
Walk fallback_order sequentially if it fails.

Supported Task Types

Task Type	Heuristic	Typical Route
`large-context`	Very large prompt/context	`gemini-cli`
`code-review`	Review/audit/refactor keywords	`claude-cli`
`fast-completion`	Short prompt	`groq`
`default`	No heuristic matched	configured default

Example `bridge.yaml`

routes:
  large-context: gemini-cli
  code-review: claude-cli
  fast-completion: groq

default: claude-cli

fallback_order:
  - claude-cli
  - gemini-cli
  - opencode-cli
  - anthropic
  - groq

If the file is missing, the bridge is disabled and the normal router behavior is used.

Bridge Response Metadata

Field	Description
`text`	Generated text
`provider`	Provider that answered
`model`	Model used
`taskType`	Classified task type
`fallbackUsed`	Whether a non-primary provider handled it
`latencyMs`	End-to-end latency

Context Compression

The CompressorService adds background context compression with caching.

Strategies

Strategy	How It Works	Good For
`extractive`	Keeps high-scoring sentences	general text
`structural`	Preserves headings and list structure	markdown/docs
`token-budget`	Cuts to a size budget at sentence boundaries	hard token limits

Usage

import { CompressorService } from './context-compression/index.js';

const compressor = new CompressorService({
  maxCacheSize: 200,
  workerIntervalMs: 5000,
  defaultStrategy: 'extractive',
  defaultRatio: 0.5,
});

compressor.submit(longContext);
const compressed = compressor.getCompressed(longContext);
const immediate = compressor.compressNow(longContext, 'structural');
compressor.destroy();

Operational Characteristics

LRU cache for repeated content
Background worker for non-blocking pre-computation
Synchronous compression when you need the result immediately
Useful for prompt pipelines where raw context would otherwise blow up token budgets

Semantic Code Search

The code-search subsystem exposes three search modes through MCP:

keyword (default): exact/prefix/fuzzy matching with inverted index
vector: semantic similarity via dense embeddings
hybrid: RRF fusion of keyword + BM25 + vector for best results

It combines:

regex-based chunking
trigram fuzzy search
BM25 keyword scoring (via MiniSearch)
dense vector similarity (via transformer embeddings)
Reciprocal Rank Fusion (RRF) for hybrid ranking
optional multi-hop import following

Supported Languages

DEFAULT_EXTENSIONS (indexed by default) covers:

.ts, .tsx, .js, .jsx, .mjs, .cjs, .py, .go, .rs, .java, .rb, .lua

Dedicated chunk patterns exist for TypeScript/JavaScript, Python, Go, and Rust. Other indexed extensions (.java, .rb, .lua) fall back to the TypeScript/C-family chunk patterns.

MCP Search Tools

index_codebase:

{
  "rootDir": "/path/to/project",
  "extensions": [".ts", ".js"],
  "ignorePatterns": ["node_modules", "dist"]
}

code_search:

{
  "query": "authentication middleware",
  "scope": "/path/to/project",
  "limit": 10,
  "followImports": true,
  "mode": "hybrid"
}

Returned results include file path, symbol name, kind, content, line numbers, score, and related chunks when import following is enabled.

Search Modes

Mode	Description	Best For
`keyword`	Exact token matching, prefix search, trigram fuzzy fallback	Known symbol names, fast, no model needed
`vector`	Cosine similarity over 384-dim embeddings	Conceptual queries, synonyms, semantic relatedness
`hybrid`	RRF fusion of keyword + BM25 + vector	General use — combines precision + recall

Keyword mode is the default and requires no setup. It scores exact name matches highest, then prefix matches, then keyword-in-content, then trigram fuzzy similarity.

Vector mode uses a local embedding model (Xenova/all-MiniLM-L6-v2, a small 384-dimensional model). On first run the model downloads automatically from HuggingFace and caches locally. Vector search finds semantically related code even when keywords don't overlap.

Hybrid mode runs all three strategies in parallel and fuses the rankings with Reciprocal Rank Fusion (RRF). Results include rrfScore (the fused score) and methodCount (how many strategies found the result). Items found by multiple methods rank higher, giving the best overall coverage.

Embedding Model

Model: Xenova/all-MiniLM-L6-v2 (small, 384-dim)
Backend: @xenova/transformers (ONNX runtime, runs locally)
First run: model auto-downloads and caches to ~/.cache/huggingface/
Fallback: if the local model fails to load, the embedder can fall back to OpenAI API (text-embedding-3-small) when OPENAI_API_KEY is set

Environment Variables

Variable	Default	Description
`EMBEDDER_MODE`	`local`	`local` uses Xenova transformer; `api` forces OpenAI API
`OPENAI_API_KEY`	—	Fallback API embedder key (optional)
`VOYAGE_API_KEY`	—	Alternative API embedder key (optional)
`TRANSFORMERS_OFFLINE`	—	Set to `1` to use only cached model, skip download

CRDT Multi-Agent State

The shared_state MCP tool gives agents a conflict-free shared state layer.

Supported CRDTs

Type	Merge Semantics	Good For
`g-counter`	max-per-node counter merge	token/request tracking
`lww-register`	last-writer-wins by timestamp	status/assignment
`or-set`	observed-remove set	shared findings or artifacts

Example Operations

{ "op": "write", "key": "tokens", "type": "g-counter", "nodeId": "agent-1", "amount": 150 }
{ "op": "write", "key": "status", "type": "lww-register", "nodeId": "agent-1", "value": "analyzing" }
{ "op": "write", "key": "findings", "type": "or-set", "nodeId": "agent-1", "action": "add", "element": "Issue in auth.ts:42" }
{ "op": "read", "key": "findings" }
{ "op": "snapshot" }
{ "op": "merge", "snapshot": { "entries": {} } }

This is useful when multiple coding or review agents need to coordinate without central locking.

Integrations

OpenCode

Configure OpenCode to treat the gateway as an OpenAI-compatible provider.

{
  "provider": {
    "llm-gateway": {
      "name": "LLM Gateway",
      "api": "openai",
      "apiKey": "env:LLM_GATEWAY_TOKEN",
      "baseURL": "https://llm-gateway.yourdomain.com/v1",
      "models": {
        "gateway-anthropic": {
          "name": "Anthropic via Gateway",
          "id": "claude-sonnet-4-20250514",
          "contextWindow": 200000,
          "maxOutput": 8192
        },
        "gateway-groq": {
          "name": "Groq via Gateway",
          "id": "llama-3.3-70b-versatile",
          "contextWindow": 128000,
          "maxOutput": 4096
        }
      }
    }
  }
}

export LLM_GATEWAY_TOKEN="your-gateway-auth-token"
opencode

GHAGGA

GHAGGA can use the bridge as a provider.

Select LLM Gateway in the GHAGGA dashboard.
Enter the gateway base URL.
Enter the gateway bearer token.
Pick a model.

Typical review modes routed through the gateway:

simple
workflow
consensus

Any OpenAI-Compatible Tool

General settings:

Setting	Value
Base URL	`https://llm-gateway.yourdomain.com/v1`
API Key	your `LLM_GATEWAY_AUTH_TOKEN`

Works with LangChain, LlamaIndex, Cursor, Continue, and any HTTP client that can call /v1/chat/completions.

LangChain Python example:

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    base_url="https://llm-gateway.yourdomain.com/v1",
    api_key="your-gateway-token",
    model="claude-sonnet-4-20250514",
)

response = llm.invoke("Explain quicksort")
print(response.content)

LangChain TypeScript example:

import { ChatOpenAI } from '@langchain/openai';

const llm = new ChatOpenAI({
  configuration: {
    baseURL: 'https://llm-gateway.yourdomain.com/v1',
  },
  apiKey: 'your-gateway-token',
  model: 'claude-sonnet-4-20250514',
});

const response = await llm.invoke('Explain quicksort');

Docker Deployment

Docker Compose

services:
  llm-gateway:
    build: .
    ports:
      - "3456:3456"
    volumes:
      - llm-data:/root/.llm-gateway
    environment:
      - LLM_GATEWAY_PORT=3456
      - LLM_GATEWAY_AUTH_TOKEN=your-secure-token-here
      - LLM_GATEWAY_MASTER_KEY=your-64-char-hex-key
volumes:
  llm-data:

docker compose up -d

Docker Build and Run

docker build -t llm-gateway .

docker run -d \
  -p 3456:3456 \
  -v llm-data:/root/.llm-gateway \
  -e LLM_GATEWAY_AUTH_TOKEN="your-token" \
  -e LLM_GATEWAY_MASTER_KEY="your-64-char-hex-key" \
  llm-gateway

What the Image Includes

The Dockerfile currently installs:

pnpm 9
OpenCode CLI
Claude Code CLI
Gemini CLI
Codex CLI
Qwen CLI
GitHub Copilot CLI

Coolify

Create a new service pointing at this repository.
Use the Dockerfile build pack.
Set environment variables such as LLM_GATEWAY_PORT, LLM_GATEWAY_AUTH_TOKEN, and optionally LLM_GATEWAY_MASTER_KEY.
Mount a persistent volume at /root/.llm-gateway.
Use /health for health checks.

MCP Server

The project runs as an MCP stdio server by default.

Primary MCP Tools

Tool	Description
`llm_generate`	Generate text with provider routing and fallback
`llm_models`	List available models
`vault_store`, `vault_list`, `vault_delete`	API key management
`vault_store_file`, `vault_list_files`, `vault_delete_file`	Auth-file management
`code_search`, `index_codebase`	Semantic code search
`shared_state`	CRDT shared state
`list_groups`, `create_group`, `delete_group`	Provider group management
`usage_summary`, `usage_query`	Cost and usage inspection
`configure_circuit_breaker`, `circuit_breaker_stats`	Provider failure-control tuning
`discover_models`	Trigger HuggingFace-enriched model discovery
`approval_list`, `approval_approve`, `approval_deny`	Approval-flow management (see Approval Flows)

PageIndex Conversation Tools

Seven additional static MCP tools (defined in src/pageindex/tools.ts) handle long-conversation pagination and reasoning-based navigation over stored conversation history:

Tool	Description
`conversation_paginate`	Paginate a stored conversation
`conversation_get_page`	Fetch a specific page
`conversation_context`	Retrieve context around a point in the conversation
`conversation_navigate`	Navigate between pages/sections
`conversation_info`	Summary/metadata for a conversation
`conversation_find_relevant`	Find the most relevant pages for a query
`conversation_check_compaction`	Check whether the conversation should be compacted

These are categorized as read tools, so they are available under both local-dev and restricted security profiles.

Claude Code Config

Add to ~/.config/claude/mcp.json:

{
  "mcpServers": {
    "llm-bridge": {
      "command": "mcp-llm-bridge"
    }
  }
}

For a local source checkout:

{
  "mcpServers": {
    "llm-bridge": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-llm-bridge/src/index.ts"]
    }
  }
}

Claude Desktop Config

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "llm-bridge": {
      "command": "mcp-llm-bridge"
    }
  }
}

MCP stdio runs locally and does not use the HTTP bearer-token middleware.

Dynamic MCP Servers

The bridge supports loading external .mcp-server.js plugin files at runtime. This lets you extend the toolset without modifying the core codebase.

What It Is

Any .mcp-server.js file placed in the plugin directory is loaded at startup and its tools are registered alongside the static tools (30 at time of writing: 23 core tools plus 7 PageIndex conversation tools). Plugins export a McpServerDefinition object (or use the builder) with tools, resources, and prompts.

Enable

Set MCP_DYNAMIC_SERVERS=true:

export MCP_DYNAMIC_SERVERS=true
export MCP_SERVERS_DIR=./mcp-servers

Create a Plugin

Create a .mcp-server.js file in the plugin directory:

import { McpServerBuilder } from 'mcp-llm-bridge/mcp-builder';

export default new McpServerBuilder()
  .tool('greet', 'Say hello to someone', { name: { type: 'string' } }, async ({ name }) => {
    return { content: [{ type: 'text', text: `Hello, ${name}!` }] };
  })
  .build();

The builder validates naming conventions, schema completeness, and description quality. Tools are registered on the MCP server and appear in ListTools.

Security

Dynamic tools are registered with the read category by default. This means they are:

Allowed under local-dev and restricted profiles
Blocked under the open profile (which only allows generate tools)

The enforcer applies the same category-based filtering to dynamic tools as it does to static tools.

Coexistence with Static Tools

Static tools (vault, search, generate, etc.) and dynamic tools appear together in the ListTools response. There is no namespacing — tool names must be unique across both sets. The approval flow and rate limiting apply uniformly to all tools.

Configuration

Core Environment Variables

Variable	Default	Description
`LLM_GATEWAY_PORT`	`3456`	HTTP server port
`LLM_GATEWAY_DB_PATH`	`~/.llm-gateway/vault.db`	SQLite vault path
`LLM_GATEWAY_MASTER_KEY`	auto-generated	64-char hex key, otherwise saved to `~/.llm-gateway/master.key`
`LLM_GATEWAY_AUTH_TOKEN`	unset	Bearer token for HTTP routes
`LLM_GATEWAY_AUTH_REQUIRED`	unset	Force auth on or off explicitly
`LLM_GATEWAY_SECURITY_PROFILE`	`local-dev`	Security profile for MCP tool exposure

Optional Runtime Features

Variable	Effect
`FALLBACK_STRATEGY=free-models`	enables free-model fallback routing
`FREE_MODEL_CATALOG=true`	loads the free-model catalog at startup
`LATENCY_ROUTING=true`	enables latency-based routing
`MAX_COMPARISON_COST_USD`	caps comparison-service spending

Master Key Priority

LLM_GATEWAY_MASTER_KEY
existing ~/.llm-gateway/master.key
auto-generated new key written with mode 0600

If you lose the master key, stored credentials are unrecoverable. Back it up in production.

Bridge Config Path

~/.llm-gateway/bridge.yaml

If that file does not exist, bridge routing is disabled.

Security Profiles

Security profiles enforce trust-level-based access control on both MCP tools and HTTP endpoints. Three profiles are built-in:

Profile	Allowed Categories	Rate Limit	Sandbox
`local-dev`	all (destructive, read, generate, admin)	none	false
`restricted`	read + generate only	100 req / 15 min	false
`open`	generate only	10 req / 15 min	false

Configuration

Set via environment variable:

LLM_GATEWAY_SECURITY_PROFILE=restricted

Default is local-dev (backward compatible — no restrictions).

Each profile also carries a sandbox flag (default false). Today this flag is best understood as prepared infrastructure, not a guarantee of sandboxed runtime execution: it is exposed on the profile schema and through the admin API, and the repo includes a Docker/process sandbox runner under src/sandbox/, but the active runtime does not yet expose sandboxed execution tools or route normal tool execution through that runner. Also note that the helper falls back to plain process execution with a timeout when Docker is unavailable, so this should not be treated as complete containment.

HTTP Enforcement

Under restricted or open, the gateway blocks destructive HTTP endpoints (e.g., POST /v1/credentials) and returns:

{ "error": "Access denied: endpoint blocked by security profile", "code": "SECURITY_PROFILE_DENIED" }

Read endpoints (GET /v1/providers, GET /v1/models) remain open under restricted.

MCP Enforcement

Under non-local-dev profiles, ListTools returns only tools in the allowed categories. CallTool is authorized before execution. Rate limiting is applied per profile.

Approval Flows

Destructive MCP tools can be paused for explicit human approval when the security profile is not local-dev.

How It Works

Client calls a destructive tool (e.g., vault_store).
If approval is required, the gateway returns an approvalRequired payload with a requestId.
Admin reviews pending requests via GET /v1/approvals or approval_list MCP tool.
Admin approves or denies via POST /v1/approvals/:id/approve or approval_approve MCP tool.
Original tool executes only after approval.

Auto-Approve List

Read-only tools (file_read, search, list, vault_list) bypass approval automatically.

HTTP Endpoints

Endpoint	Method	Description
`/v1/approvals`	GET	List pending approval requests
`/v1/approvals/:id/approve`	POST	Approve a request
`/v1/approvals/:id/deny`	POST	Deny a request

MCP Tools

Tool	Description
`approval_list`	List pending requests
`approval_approve`	Approve by request ID
`approval_deny`	Deny by request ID

Three-Part Prompt

The three-part prompt pattern separates prompts into system (role/constraints), context (background data), and instruction (the actual task). Research shows measurable quality improvement, especially with smaller models.

HTTP API

Both /v1/generate and /v1/chat/completions accept the three fields:

curl -X POST http://localhost:3456/v1/generate \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{
    "system": "You are a code reviewer.",
    "context": "We use Zod 4 and Hono.",
    "instruction": "Review this schema for edge cases."
  }'

Legacy flat prompt is still accepted and auto-detected when system/context/instruction are absent.

MCP Schema

The llm_generate tool exposes system, context, and instruction as optional fields alongside the legacy prompt:

{
  "system": "You are a helpful assistant.",
  "context": "The project uses TypeScript.",
  "instruction": "Explain strict mode benefits."
}

Enable/Disable

OPTIMIZE_MESSAGES_ENABLED=true   # default: true

RTK Output Compression

RTK-style compression strips redundant content from tool call results before passing them to LLMs. This saves token budget on large structured outputs.

Strategies

Filter — remove noise fields (created_at, id, etag, etc.)
Group — merge repeated similar entries into count + sample
Truncate — enforce max length on string values
Deduplicate — remove exact-duplicate array entries

Configuration

ENABLE_OUTPUT_COMPRESSION=true   # default: true

Analytics Endpoint

curl http://localhost:3456/v1/compression/stats \
  -H 'Authorization: Bearer YOUR_TOKEN'

Response:

{ "totalCalls": 42, "compressedCalls": 42, "avgRatio": 0.65, "totalSavingsChars": 15200 }

Local LLM Offloading

Offloadable tasks (summarization, formatting, classification) can be routed to local runtimes (Ollama, LM Studio) instead of cloud providers, cutting API token cost on those deterministic tasks. (The src/local-llm/ module documents an 86–95% design target for token savings on boilerplate tasks; this is a design goal, not a measured benchmark.)

Environment Variables

Variable	Default	Description
`LOCAL_LLM_ENABLED`	`false`	Enable local LLM routing
`OLLAMA_URL`	`http://localhost:11434`	Ollama API endpoint
`LM_STUDIO_URL`	`http://localhost:1234`	LM Studio API endpoint

Detection

At startup, the gateway probes both backends. Models are listed at:

curl http://localhost:3456/v1/local/models \
  -H 'Authorization: Bearer YOUR_TOKEN'

Fallback

If the local LLM fails or the task is not offloadable, the gateway falls back to cloud providers automatically and emits a metric.

MCP Tool

Tool	Description
`local_llm_generate`	Generate via local LLM with offload detection

Model Routing

Model routing adds task-aware provider selection that classifies each prompt and routes it based on configured rules, preferred endpoint order, cost tiers, and observed quality feedback.

What It Does

Classifies incoming prompts into runtime task types such as code-review, large-context, fast-completion, summarization, and translation
Matches the task against routing rules defined in model-routing.json
Tries preferred endpoints in rule order while enforcing the configured cost cap
Falls back to more expensive endpoints if quality drops below threshold
Learns from feedback — records success/failure per endpoint+task for adaptive routing

Enable

MODEL_ROUTING_ENABLED=true

When enabled, the precedence stack becomes:

Session stickiness
Group-based routing
ModelRouter (task-aware selection)
Local-LLM offloading (only if ModelRouter is disabled or returns no match)
Standard resolution (model match → provider preference → API before CLI)
Latency reordering

Configuration

Create model-routing.json in the project root. The gateway loads it at startup.

{
  "enabled": true,
  "endpoints": [...],
  "rules": [...],
  "defaultEndpoint": "opencode-cli-default",
  "qualityThreshold": 0.7,
  "qualityWindowSize": 50
}

Field	Type	Description
`enabled`	boolean	Whether model routing is active
`endpoints`	array	Available model endpoints with cost tier and capabilities
`rules`	array	Task-to-endpoint routing rules (first match wins)
`defaultEndpoint`	string	Fallback endpoint ID when no rule matches
`qualityThreshold`	number	Minimum acceptable quality rate (0–1)
`qualityWindowSize`	number	Number of recent requests to track per endpoint+task

Endpoint fields:

Field	Type	Description
`id`	string	Unique endpoint identifier
`providerId`	string	Provider ID (e.g., `anthropic`, `openai`, `opencode-cli`)
`model`	string	Model ID for API calls
`costTier`	string	`free`, `cheap`, `standard`, or `expensive`
`capabilities`	array	Capability tags (e.g., `chat`, `code`, `reasoning`)
`maxTokens`	number	Maximum context window in tokens

Rule fields:

Field	Type	Description
`id`	string	Unique rule identifier
`taskType`	string	One of `large-context`, `code-review`, `fast-completion`, `default`, `boilerplate`, `commit-message`, `format-conversion`, `style-check`, `summarization`, `translation`, `not-offloadable`, or `*`
`preferredEndpoints`	array	Ordered list of endpoint IDs to try
`maxCostTier`	string	Most expensive tier allowed for this task
`allowFallback`	boolean	Whether to fall back to default endpoint if all preferred fail

Example Task-to-Endpoint Mappings

Task Type	Preferred Endpoints	Cost Cap
`code-review`	Claude Sonnet → GPT-4.1	`expensive`
`large-context`	Claude Sonnet → GPT-4.1	`expensive`
`fast-completion`	GPT-4.1-mini → OpenCode CLI	`standard`
`summarization`	GPT-4.1 → Claude Sonnet	`expensive`
`*` (default)	OpenCode CLI → GPT-4.1-mini	`standard`

Coexistence with Local-LLM Offloading

Local-LLM offloading and model routing work together with clear precedence:

ModelRouter runs first. If it selects an endpoint, that provider is promoted to the top of the candidate list.
Local-LLM offloading runs only when ModelRouter is disabled or returns no match. This prevents conflicts: explicit routing rules always beat heuristic offloading.

If you want local models in your routing mix, register them as endpoints with "costTier": "free" and include them in rule preferredEndpoints.

Example File

See model-routing.example.json in the repository root for a full template with multiple endpoints and routing rules.

HF Auto-Discovery

At startup (when enabled), the gateway scans local backends and enriches detected models with HuggingFace metadata (tags, pipeline type, recommended tasks).

Configuration

AUTO_DISCOVER_MODELS=true   # default: false
HF_TOKEN=hf_xxxxxxxxxx       # optional, for private repos

Admin Endpoint

Trigger discovery on demand:

curl -X POST http://localhost:3456/v1/admin/discover \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "hfToken": "optional-override" }'

Response:

{
  "ok": true,
  "backendsScanned": ["ollama", "lm-studio"],
  "models": [...],
  "enrichedCount": 3,
  "unenrichedCount": 1
}

Cache

Enriched metadata is persisted to SQLite (hf_model_cache table) so subsequent startups are fast even without HF API access.

Architecture

Clients (GHAGGA, OpenCode, curl, LangChain, any OpenAI-compatible tool)
    |
    |  POST /v1/chat/completions  |  POST /v1/generate  |  MCP stdio
    v
+-------------------------------------------------------------------+
|                    MCP LLM Bridge (Hono + MCP)                    |
|                                                                   |
|  HTTP Server                       MCP Server                     |
|  - /v1/chat/completions            - llm_generate                 |
|  - /v1/generate                    - vault_*                      |
|  - /v1/models                      - code_search                  |
|  - /v1/providers                   - index_codebase               |
|  - /v1/credentials CRUD            - shared_state                 |
|  - /v1/files CRUD                  - usage_*                      |
|  - /v1/groups CRUD                 - circuit_breaker_*            |
|  - /metrics /health                - group tools                  |
|  - /v1/compression/stats           - approval_*                   |
|  - /v1/local/models                - local_llm_generate           |
|  - /v1/admin/discover              - discover_models              |
+-------------------------------------------------------------------+
|  Bridge routing         | Context compression | Code search        |
|  Provider groups        | Cost tracking       | CRDT state         |
|  Security profiles      | Approval flows      | Local LLM          |
|  HF discovery           | Three-part prompt   | Output compression |
+-------------------------+---------------------+--------------------+
| Router (model -> provider)       | Vault (AES-256-GCM + SQLite)   |
+-------------------------+---------------------+--------------------+
    |                                                  |
    v                                                  v
  API providers                                   CLI providers
  Anthropic, OpenAI, Google, Groq, OpenRouter     OpenCode, Claude,
                                                   Gemini, Codex, Qwen, Copilot

Design Notes

Hono keeps the HTTP layer small and fast.
better-sqlite3 keeps the vault single-file and operationally simple.
SQLite WAL mode improves concurrent read behavior.
API providers are preferred before CLI providers unless bridge logic says otherwise.
Vault writes use upsert semantics for repeatable automation.
CLI adapters materialize auth files into temp homes and clean them up in finally blocks.
Bridge routing is intentionally optional and file-driven.
Code search stays in-memory for speed and freshness.
CRDTs reduce coordination pain for parallel agent workflows.

Experimental Modules

src/acp/ — Agent Client Protocol implementation (server.ts, translator.ts, types.ts).
Present in the repo but not wired into the active runtime. There is no import path from src/index.ts, no active HTTP/stdio ACP transport, and no live MCP tool-execution bridge yet. Treat it as a tested protocol prototype that still needs a dedicated ACP integration sprint.
src/sandbox/ — Docker/process sandbox runner.
The sandbox flag now exists in security profiles, but the runtime still does not expose sandboxed execution tools like execute_code or shell_command. In other words: the infrastructure is prepared, but the feature is not complete.

Session Systems

The gateway now uses SessionManager for both session-affinity concerns:

Router sticky sessions (SessionManager.pinRouterStickySession) — Pins a specific clientId + model to a provider/key with TTL-based expiry.
Group/API sessions (src/session/session-manager.ts) — Manages session affinity for multi-turn conversations and dashboard metrics.

They are separate by design inside the same manager instance: router stickiness handles provider selection, while group/API sessions handle conversation continuity.
Do not conflate the two entry kinds.

GET /v1/admin/sessions reports them separately for that reason:

routerStickySessions comes from SessionManager router-sticky entries and reflects the pins the Router actually uses at request time.
groupSessions comes from SessionManager and reflects group-level session affinity metrics.
The endpoint includes a note explaining the split so the dashboard does not imply a single shared session pool.

Security

AES-256-GCM encryption for stored keys and auth files
constant-time bearer-token comparison
master key file stored with mode 0600
config directory created with mode 0700
credentials are never returned raw from listing endpoints
temp auth files are cleaned up after CLI invocations
minimum 32-character auth token requirement
public /health endpoint for safe monitoring

Development

pnpm run dev
pnpm run serve
pnpm run start
pnpm test
pnpm run typecheck
pnpm run build

Scripts

Script	Command	Description
`start`	`tsx src/index.ts`	MCP stdio mode
`dev`	`tsx watch src/index.ts`	local development
`serve`	`tsx src/index.ts serve`	HTTP server and dashboard
`test`	`node --import tsx --import ./test/setup/inject-require.mjs --test test/.test.ts test//.test.ts`	test suite
`build`	`tsup src/index.ts --format esm --dts`	production build
`typecheck`	`tsc --noEmit`	TypeScript checking

Requirements

Node.js 22+
pnpm 9+

License

MIT, as declared in package.json ("license": "MIT"). Note: a standalone LICENSE file is not yet committed to the repository.

Available Tools

30 tools

approval_approveB

Approve a pending request by ID.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Approval request ID

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full responsibility for behavioral disclosure. It only states the basic action, without mentioning permissions, side effects, or what happens if the request is already approved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence of 6 words, efficiently conveying the tool's purpose without unnecessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema, the description is minimally adequate. It states the action but lacks context about the result or effect of approving, which would be helpful for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The parameter 'id' is fully described in the schema as 'Approval request ID'. The description does not add any additional meaning beyond the schema, which already covers 100% of parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Approve a pending request by ID' clearly specifies the action (approve) and the resource (pending request). It effectively distinguishes from sibling tools like approval_deny and approval_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for approving a pending request, but does not provide explicit guidance on when to use versus alternatives (e.g., approval_deny) or any prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

approval_denyA

Deny a pending request by ID.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Approval request ID

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, and description only states the action. Lacks disclosure of side effects, authorization needs, or state changes beyond 'deny'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy, efficient for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for basic understanding but omits potential error conditions, required permissions, or outcome feedback. No output schema to compensate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with parameter 'id' described. Description adds 'by ID' but doesn't clarify format or constraints beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states action (deny) and resource (pending request by ID). Distinguishes from sibling tools approval_approve and approval_list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage for denying requests but provides no explicit guidance on when to use this tool versus alternatives like approval_approve.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

approval_listB

List pending approval requests.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description only states 'list,' indicating a read operation, but lacks details on what 'pending' means, result format, pagination, or ordering. Beyond the basic action, transparency is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise at one sentence, but communicates the essential purpose. No wasted words, though lacks structure like sections or bullet points.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, output schema, or annotations, the description is too minimal. It does not clarify the scope of 'pending' or any filtering, leaving the agent with insufficient context for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. The description adds no parameter information, but per guidelines, baseline is 4 with 0 parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'list pending approval requests,' identifying the verb and resource. Distinguishes from sibling tools approval_approve and approval_deny, which perform actions on such requests.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives. However, context with siblings (approve/deny) implies it is for viewing pending requests before acting.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

circuit_breaker_statsA

Get circuit breaker stats for all providers. Shows state, failures, successes, cooldown.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It states what is shown (state, failures, successes, cooldown) but does not disclose behavioral traits like whether it is read-only, destructive, or requires special permissions. It is minimally adequate but could be improved.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences that cover the purpose and output. Every word earns its place; there is no fluff. Front-loaded with the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description provides a reasonable overview of what the tool returns. It mentions key fields (state, failures, successes, cooldown). It could be enhanced by noting it is a safe, read-only operation, but overall it is fairly complete for a zero-parameter stats tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters and schema coverage is 100%. The description does not need to add parameter-specific meaning. Baseline for 0 parameters is 4. No issues.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'circuit breaker stats for all providers'. It is specific and distinguishes from sibling tools like configure_circuit_breaker, though not explicitly. A score of 4 is appropriate because it is clear but lacks explicit sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool vs alternatives. Siblings like configure_circuit_breaker exist but are not referenced. The description does not mention exclusions or typical usage scenarios, limiting its utility for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

code_searchB

Search code semantically. Finds functions, classes, and blocks matching a query using keyword + fuzzy matching. Optionally follows imports for related code.

ParametersJSON Schema

Name	Required	Description	Default
`mode`	No	Search strategy: keyword (exact/prefix/fuzzy), vector (semantic similarity), or hybrid (RRF fusion of all)	keyword
`limit`	No	Maximum results to return (default: 10, max: 50)
`query`	Yes	Search query (e.g. "authentication middleware", "database connection")
`scope`	No	Directory path to limit search scope (default: current working directory)
`followImports`	No	Follow imports to find related code chunks (default: false)

TDQS

B3.4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses search scope, mode options, and optional import-following, but does not mention side effects, performance characteristics, or result behavior (e.g., pagination, truncation).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first states core functionality, second adds a notable optional feature. No redundant information, efficient and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderate complexity and no output schema, the description covers the main behavior (search, follow imports) and mentions mode options indirectly. It lacks details about result format but is largely complete for a search tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds general context (e.g., 'keyword + fuzzy matching') but does not elaborate on individual parameters beyond what the schema provides. No significant semantic enhancement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: searching code semantically using keyword and fuzzy matching, targeting functions, classes, and blocks. It also mentions optional import-following. However, it does not explicitly distinguish from sibling tools like 'index_codebase', though most siblings are unrelated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives or when not to use it. The description lacks usage context, prerequisites, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

configure_circuit_breakerB

Configure circuit breaker settings. Updates thresholds and backoff for all breakers.

ParametersJSON Schema

Name	Required	Description
`backoffMaxMs`	No	Maximum backoff cap in ms (default: 300000 = 5 min)
`backoffBaseMs`	No	Exponential backoff base in ms (default: 5000). Set to enable backoff.
`resetTimeoutMs`	No	Fixed timeout before half-open in ms (default: 30000)
`failureThreshold`	No	Number of failures before opening (default: 5)
`backoffMultiplier`	No	Exponential backoff multiplier (default: 2)

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, description carries full burden. It only says 'configures' and 'updates', but does not disclose side effects, permissions, reversibility, or scope (global vs per-circuit). Minimal behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two clear, front-loaded sentences with no wasted words. Efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 optional parameters and no output schema, description gives high-level purpose but lacks details like return value, default behavior, or scope. Adequate but not comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with each parameter having descriptions and defaults. The description adds little beyond 'thresholds and backoff'. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it configures circuit breaker settings, specifically thresholds and backoff, and updates all breakers. It distinguishes from sibling tools like circuit_breaker_stats which is read-only.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance when to use this tool vs alternatives, no prerequisites or exclusions provided. The description lacks usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

conversation_check_compactionB

Check if conversation needs compaction for given model context limit

ParametersJSON Schema

Name	Required	Description
`session_id`	Yes	Session identifier
`model_max_tokens`	Yes	Model context window size (e.g., 4096)
`additional_tokens`	No	Additional tokens to be added (default: 0)

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as side effects, permission requirements, or whether the tool is read-only. It only states what the tool checks, not what happens during the check.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks information about the return value (e.g., boolean or status), which is critical since there is no output schema. For a simple check tool, this omission makes the description incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds context about the overall purpose but does not enhance parameter semantics beyond what the schema already provides (e.g., session_id, model_max_tokens, additional_tokens).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Check' and the resource 'if conversation needs compaction' with the condition 'for given model context limit', making the tool's purpose specific and distinguishable from sibling tools like conversation_context or conversation_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives (e.g., conversation_context), when not to use it, or any prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

conversation_contextA

Get a page with surrounding context pages. Use this for reading with context.

ParametersJSON Schema

Name	Required	Description
`page_num`	Yes	Target page number
`session_id`	Yes	Session identifier
`window_size`	No	Number of pages before and after (default: 1)

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It fails to disclose any behavioral traits beyond the basic read operation, such as rate limits, authentication, error handling, or what happens if the page or context is unavailable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no redundancy. First sentence states what the tool does, second advises when to use it. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema is provided, and the description does not explain what is returned (e.g., page content, surrounding pages, metadata). It also lacks edge-case handling or return format details, making it incomplete for a tool with 3 parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the input schema already provides for page_num, session_id, and window_size.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Get') and resource ('a page with surrounding context pages'), clearly distinguishing it from sibling tools like conversation_get_page (single page) or conversation_navigate (navigation). The phrase 'reading with context' further clarifies its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use the tool ('for reading with context'), providing clear context. However, it does not mention when not to use or alternatives among siblings, which would elevate it to a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

conversation_find_relevantC

Find pages relevant to a query using keyword matching

ParametersJSON Schema

Name	Required	Description
`query`	Yes	Search query (keywords)
`max_pages`	No	Maximum pages to return (default: 2)
`session_id`	Yes	Session identifier

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description mentions 'keyword matching' but lacks behavioral details such as whether it searches across sessions, how relevance is determined, or output format. With no annotations, the burden is on the description, which is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no waste. However, it could be expanded to include more context without becoming verbose, so it's slightly under-specified.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema and no annotations, the description provides minimal context. It doesn't explain what 'pages' refers to, or any constraints, making it incomplete for an agent to fully understand tool behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description does not add any additional meaning beyond the schema's parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool finds pages relevant to a query using keyword matching, giving a specific verb, resource, and method. It distinguishes from siblings like conversation_get_page and conversation_paginate, though not explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance provided on when to use this tool vs alternatives. The description only states what it does, not the context or when to prefer it over other conversation tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

conversation_get_pageC

Get a specific page from a paginated conversation

ParametersJSON Schema

Name	Required	Description	Default
`page_num`	Yes	Page number (1-based)
`session_id`	Yes	Session identifier

TDQS

C2.8/5.0

Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description does not disclose any behavioral traits such as whether it is read-only, required authentication, or behavior for invalid page numbers.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is concise but under-specified. Lacks important context that would justify its brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simple tool with no output schema, description still lacks details on page content, error handling, or prerequisites. Incomplete for an agent to reliably invoke.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with descriptions for both parameters. Description adds no additional meaning beyond schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'get' and resource 'specific page from a paginated conversation'. It distinguishes from sibling tools like conversation_paginate and conversation_info.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives like conversation_paginate or conversation_navigate. Implicitly assumes agent knows when to fetch a specific page.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

conversation_infoA

Get info about a paginated conversation: total pages, total tokens, etc.

ParametersJSON Schema

Name	Required	Description	Default
`session_id`	Yes	Session identifier

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It implies a read operation but does not explicitly state that it is read-only, nor does it disclose any side effects, authentication requirements, or rate limits. The mention of return fields provides minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no extraneous content. It is well front-loaded, stating the verb and resource immediately, followed by examples of the returned data.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple info tool with one parameter and no output schema, the description gives a reasonable overview of the return values. However, it lacks details on output format, error handling, or the meaning of 'etc.', leaving some ambiguity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter session_id, which is described as 'Session identifier'. The description does not add any additional meaning or context for the parameter beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it retrieves metadata about a paginated conversation (total pages, total tokens). It distinguishes from sibling tools like conversation_get_page or conversation_paginate, which focus on content or navigation. However, it does not explicitly differentiate from conversation_context, which might overlap.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives. The name and description imply it's for metadata, but there is no statement about when not to use it or which sibling tool to choose for other needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

conversation_navigateC

Navigate to next, previous, first, or last page

ParametersJSON Schema

Name	Required	Description
`direction`	Yes	Navigation direction
`session_id`	Yes	Session identifier
`current_page_num`	Yes	Current page number

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose side effects, authentication requirements, or whether the tool modifies state. The behavioral impact of navigation is unclear.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very short and front-loaded, conveying the core purpose efficiently. It could benefit from slightly more detail, but it remains concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of output schema and minimal description, the tool's behavior after navigation (e.g., return values) is missing. Contextual completeness is lacking for a simple but actionable navigation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already documents all three parameters. The description adds no extra meaning beyond the schema; thus base score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool navigates to specific pages (next, previous, first, last), which is a specific verb+resource. It distinguishes from siblings like conversation_get_page and conversation_paginate, though it could be more explicit about the context of conversation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like conversation_get_page or conversation_paginate. This leaves the agent without context on selecting the correct tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

conversation_paginateA

Divide a long conversation into navigable pages. Use this when conversation exceeds safe context limits.

ParametersJSON Schema

Name	Required	Description	Default
`content`	Yes	Full conversation content to paginate
`session_id`	Yes	Unique session identifier

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must carry full burden. It only states the high-level action without disclosing side effects, output format, authentication needs, or whether the tool modifies state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The purpose and usage condition are front-loaded, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no output schema), the description is adequate but lacks details on return format or integration with sibling tools. Missing information on what 'navigable pages' means in practice.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and both parameters are described in the schema. The description adds no extra meaning beyond what the schema already provides, meeting the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool divides long conversations into pages, using specific verb 'divide' and resource 'long conversation'. However, it does not explicitly distinguish from sibling tools like conversation_get_page or conversation_navigate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a clear condition for use: 'when conversation exceeds safe context limits'. No exclusions or alternatives mentioned, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_groupB

Create a new provider group for load balancing.

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Group name (e.g. "anthropic-keys", "fast-models")
`members`	Yes	Array of provider members: [{ provider, keyName?, weight?, priority? }]
`strategy`	Yes	Balancing strategy: "round-robin", "random", "failover", "weighted"
`stickyTTL`	No	Session stickiness TTL in seconds (optional)
`modelPattern`	No	Glob pattern to match model names (e.g. "claude-", "gpt-,claude-*")

TDQS

B3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only says 'create a new provider group for load balancing' — missing side effects, auth needs, or duplicate handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no fluff, but could be more informative without sacrificing brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no annotations, yet the description omits return values, error cases, and behavioral details; incomplete for a 5-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers 100% of parameters with descriptions, so the tool description adds little beyond the schema; baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('create') and resource ('provider group for load balancing'), and distinguishes it from sibling tools like 'delete_group' and 'list_groups'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_groupB

Delete a provider group by its ID.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Group ID to delete

TDQS

B3.3/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description carries full burden. It only states the action but does not disclose side effects (e.g., irreversible deletion, cascading effects, permission requirements, or rate limits).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise single sentence with no fluff. Every word is necessary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no nested objects), the description is minimally adequate but lacks behavioral and usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a clear 'Group ID to delete' description. The tool description adds no extra meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Delete) and the resource (provider group) with the identifier (by its ID). It is specific and distinct from sibling tools like create_group or list_groups.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool or alternatives. It does not mention prerequisites, such as ensuring the group is not in use, or that deletion is irreversible.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

discover_modelsA

Discover local LLM models and enrich them with HuggingFace metadata. Returns enriched model list with capabilities and recommended tasks.

ParametersJSON Schema

Name	Required	Description	Default
`hfToken`	No	Optional HuggingFace API token for gated model access

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must disclose behavioral traits. It mentions enriching with HuggingFace metadata, hinting at network calls, but does not explicitly state side effects (e.g., read-only, no modifications) or authentication needs beyond the optional hfToken. The description is adequate but lacks full transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise, consisting of two short sentences that front-load the main purpose and output. Every sentence is meaningful with no redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (1 optional param, no output schema), the description adequately conveys the action and output. It mentions 'capabilities and recommended tasks' which hints at output structure, but could be improved by explicitly stating network dependence or output fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema description coverage, the schema already describes the optional hfToken parameter. The tool description does not add additional context about token usage or parameter semantics, so it provides no extra value beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool discovers local LLM models and enriches them with HuggingFace metadata, specifying the result as an enriched model list with capabilities and recommended tasks. This distinguishes it from sibling tools like llm_models (likely a simple list) and local_llm_generate (text generation).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for discovering and enriching models but does not provide explicit when-to-use or when-not-to-use guidance. No alternatives or exclusion criteria are mentioned, leaving the agent to infer usage context from sibling tool names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

index_codebaseA

Index a codebase directory for semantic code search. Scans files, extracts functions/classes/blocks, and builds an in-memory search index.

ParametersJSON Schema

Name	Required	Description
`rootDir`	No	Root directory to index (default: current working directory)
`extensions`	No	File extensions to index (default: .ts, .js, .py, .go, .rs, etc.)
`ignorePatterns`	No	Directory names to ignore (default: node_modules, .git, dist, etc.)

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully convey behavioral traits. It mentions building an in-memory index, which is a key trait, but does not state that it is a read-only operation, whether it modifies files, or potential performance implications. The description adds some behavioral context but leaves gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no wasted words. It is front-loaded with the primary action and provides additional detail efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks information about the output of the tool (e.g., success message, index identifier) and does not explicitly mention that the index is used by the sibling 'code_search' tool. While it mentions the purpose, the absence of output schema and return value details leaves some contextual gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents parameters. The description adds no additional meaning about parameters beyond what the schema provides. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool indexes a codebase for semantic code search, specifying it scans files, extracts functions/classes/blocks, and builds an in-memory search index. This distinguishes it from sibling 'code_search' which would query the index.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is a prerequisite for code_search, but does not explicitly state when to use it versus alternatives or when not to use it. The sibling tool name 'code_search' provides context, but the description could be more explicit about the dependency.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_groupsA

List all provider groups for load balancing.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

A3.8/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states 'list all' implying read-only, but lacks details on permissions, pagination, or behavior when no groups exist. Minimal transparency for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no waste, front-loading the purpose. Efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and no output schema, the description adequately covers the tool's core function. However, it could optionally mention the intended audience or relation to load balancing setup for enhanced completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With no parameters, the schema coverage is 100% trivially. The description adds no parameter info, but none is needed. Baseline for 0 params is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List', the resource 'all provider groups', and the context 'for load balancing', distinguishing it from sibling tools like create_group or delete_group.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for viewing groups before load balancing configuration but does not explicitly state when to use this tool versus alternatives like search or filter tools (none exist) or provide conditions for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

llm_generateA

Generate text using an LLM. Routes to the best available provider with automatic fallback. Supports three-part prompts (system/context/instruction) for improved quality.

ParametersJSON Schema

Name	Required	Description
`model`	No	Specific model ID (e.g. "claude-sonnet-4-20250514", "gpt-4o", "gemini-2.5-flash", "llama-3.3-70b-versatile")
`prompt`	Yes	The user prompt to send to the LLM (legacy flat format). Use context+instruction for better results.
`strict`	No	When true, only try the first resolved provider and disable fallback.
`system`	No	Optional system prompt — role, personality, constraints
`context`	No	Background information, data, or documents for the task
`project`	No	Project scope for credential resolution (e.g. "ghagga", "md-evals"). Falls back to global credentials if not found.
`provider`	No	Preferred provider ID (e.g. "anthropic", "openai", "google", "groq", "openrouter", "cerebras", "zai", "nvidia", "mistral", "sambanova", "hyperbolic", "claude-cli")
`maxTokens`	No	Maximum output tokens (default: 4096)
`instruction`	No	The actual task or question to perform

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description must cover behavioral traits. It discloses routing and fallback behavior, but lacks details on idempotency, cost, error handling, or return format. This is adequate but incomplete.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the primary action. Every sentence adds value: main purpose, routing feature, and prompt quality tip. No redundancy or wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 9 parameters, 100% schema coverage, no output schema, and moderate complexity (routing, fallback), the description gives a good overview but fails to specify return format or error behavior. Lacks completeness for a tool with this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 9 parameters. The description adds context about using system/context/instruction together for improved quality, which is helpful but not additive beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Generate text using an LLM' and distinguishes from siblings like local_llm_generate by mentioning automatic routing and fallback. It also highlights the three-part prompt feature, making the purpose specific and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies using three-part prompts (system/context/instruction) for better quality, but does not explicitly compare to local_llm_generate or other tools. There is no guidance on when to use this tool versus alternatives, nor any exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

llm_modelsB

List all available models across registered providers.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must disclose behavioral traits. It only indicates the tool lists models, but fails to mention read-only nature, potential delays, or any side effects. The description adds no substantive behavioral context beyond the name.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, short sentence that efficiently conveys the tool's function. No extraneous information, and the key action is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool without annotations or output schema, the description is minimally adequate. It states the purpose but lacks details on providers, model types, or what 'available' means. Given the simple nature, it is somewhat complete, but could be improved by mentioning output format or restrictions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the baseline is 4. The description does not need to add parameter information, and it appropriately omits irrelevant details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists all available models across registered providers. The verb 'list' and resource 'models' are specific. However, it does not explicitly distinguish from the sibling 'discover_models', which may have a different purpose, but the distinction is implicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool vs alternatives like 'discover_models' or 'llm_generate'. The description lacks context for appropriate invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

local_llm_generateA

Generate text using a local LLM (Ollama/LM Studio) for offloadable tasks. Falls back to cloud provider if local LLM is unavailable.

ParametersJSON Schema

Name	Required	Description
`prompt`	Yes	The user prompt to send to the local LLM
`system`	No	Optional system prompt
`maxTokens`	No	Maximum output tokens (default: 4096)
`preferredModel`	No	Preferred local model ID (e.g., "llama3.2:3b")

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses the local LLM usage and fallback behavior, which is a key trait. However, it could elaborate on error handling or latency implications.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no fluff, front-loading the core purpose and key behavior.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is informative for a generation tool with good schema coverage. It covers purpose and fallback, but could mention typical use cases or limitations for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description does not need to add much. It does not provide additional details beyond the schema descriptions, resulting in baseline score.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'generate text using a local LLM' and distinguishes from sibling cloud tool 'llm_generate' by noting the local fallback behavior.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions 'for offloadable tasks', implying when to use, and notes fallback to cloud LLM, but does not explicitly state when not to use or list alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

shared_stateA

CRDT-based shared state for multi-agent collaboration. Supports conflict-free read/write/merge with G-Counter (token tracking), LWW-Register (agent status), and OR-Set (shared findings).

ParametersJSON Schema

Name	Required	Description
`op`	Yes	Operation: "read", "write", "merge", "snapshot", or "list"
`key`	No	Container key name (required for read/write)
`type`	No	CRDT type: "g-counter", "lww-register", or "or-set" (required for write)
`value`	No	Value to write (semantics depend on type)
`action`	No	Action for or-set: "add" or "remove"
`amount`	No	Increment amount for g-counter (default: 1)
`nodeId`	No	Agent/node identifier (required for write)
`element`	No	Element to add/remove for or-set
`snapshot`	No	State snapshot to merge (required for merge op)

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description carries the full burden. It mentions 'conflict-free' and 'read/write/merge' operations, but does not disclose side effects, authorization needs, rate limits, or failure modes. It adds some behavioral context beyond a bare description, but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The two-sentence description is concise and front-loaded with the purpose. Every sentence adds value, and there is no wasted text. It efficiently conveys the core functionality.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (9 parameters, nested objects, no output schema), the description does not explain return values or workflow. It adequately covers the 'what' but not the 'how' or 'what to expect', leaving gaps for an agent needing complete context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by mapping CRDT types to use cases ('token tracking', 'agent status', 'shared findings'), which enhances semantic understanding beyond the parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it is a 'CRDT-based shared state for multi-agent collaboration' and lists supported operations and CRDT types. This verb-resource combination is specific and distinguishes it from sibling tools like approval, circuit breaker, or vault, which have different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for multi-agent collaboration and state management, but does not explicitly state when to use or avoid this tool, nor does it compare with alternatives. The sibling tools are mostly unrelated, so context is clear, but explicit guidance is missing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

usage_queryC

Query individual usage records with filters. Returns raw usage log entries.

ParametersJSON Schema

Name	Required	Description
`to`	No	End date (ISO format)
`from`	No	Start date (ISO format)
`limit`	No	Maximum records to return (default: 100)
`model`	No	Filter by model
`project`	No	Filter by project
`provider`	No	Filter by provider

TDQS

C2.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries the full burden. It fails to disclose behavioral aspects such as whether the data is live or cached, ordering, pagination limits (beyond the default 100), or any side effects. The tool appears to be a read operation but this is not explicitly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise with two short sentences, no unnecessary words. However, it may be too terse given the complexity of the tool, but it is well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters, no output schema, and no annotations, the description is incomplete. It lacks information on return value structure, ordering, pagination behavior, and error handling. A more detailed description would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 6 parameters are described in the schema (100% coverage), so the description adds no additional meaning beyond 'filters'. The baseline is 3, and the description does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Query' and resource 'usage records', and specifies that it returns 'raw usage log entries'. This distinguishes it from the sibling tool 'usage_summary', which likely aggregates data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., usage_summary). There is no mention of prerequisites, context, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

usage_summaryB

Get cost/usage summary. Returns total requests, tokens, cost, with optional breakdown by provider, model, project, hour, or day.

ParametersJSON Schema

Name	Required	Description
`to`	No	End date (ISO format, e.g. "2026-03-23")
`from`	No	Start date (ISO format, e.g. "2026-03-01")
`model`	No	Filter by model
`groupBy`	No	Group breakdown by: "provider", "model", "project", "hour", "day"
`project`	No	Filter by project
`provider`	No	Filter by provider

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It fails to disclose whether the tool is read-only, any rate limits, required authentication, or side effects. It only describes the output metrics, not operational behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence that conveys the core purpose and optional breakdowns. No unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 optional parameters and no output schema, the description could explain default date ranges, behavior when no filters are set, and the output format. It covers the basics but leaves gaps for an agent to infer.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds context that the tool returns total requests, tokens, and cost, mapping to the parameters. However, schema coverage is 100%, so added value is moderate; the description does not introduce new semantics beyond reinforcing the breakdown options.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a cost/usage summary including requests, tokens, cost, and optional breakdowns. It distinguishes from vague or unrelated tools, but could be more explicit about its relation to similar tools like usage_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as usage_query. The description does not mention prerequisites, default behavior, or scenarios where one tool is preferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_deleteB

Delete a stored credential by its ID.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	Credential row ID to delete

TDQS

B3.4/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description only states the basic action. It fails to disclose potential consequences (e.g., permanent deletion, error behavior if ID not found, permission requirements).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence with no extraneous words. It is efficiently front-loaded and directly states the tool's purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple delete operation with one required parameter and no output schema, the description is sufficiently complete. However, it could briefly note that the deletion is permanent or irreversible, which would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter. The description adds no extra information beyond what the schema already provides, so it meets the baseline but does not enhance understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Delete') and resource ('stored credential') with a clear identifier ('by its ID'). It is unambiguous and distinguishes from sibling tools like vault_delete_file which deletes a file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use or not use this tool. Alternatives such as vault_list or vault_store are not mentioned. The description provides no context for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_delete_fileB

Delete a stored auth file by its ID.

ParametersJSON Schema

Name	Required	Description	Default
`id`	Yes	File row ID to delete

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. It only states 'Delete a stored auth file' without details on permissions, reversibility, side effects, or whether the deletion is permanent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence that immediately conveys the action and resource. No extraneous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple delete operation with one parameter, the description is minimal. It fails to differentiate from vault_delete, lacks information about return values or confirmation, and does not explain what happens after deletion. Given no output schema, more context would be beneficial.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the parameter description is already adequate. The tool description does not add additional semantics beyond what the schema provides, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Delete' and the resource 'stored auth file', and specifies the identifier 'by its ID'. This distinguishes it from siblings like vault_delete (which may delete other vault items) and vault_store_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives such as vault_delete. The description does not mention prerequisites, context, or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_listA

List all stored credentials with masked values. Optionally filter by project.

ParametersJSON Schema

Name	Required	Description	Default
`project`	No	Filter by project (shows project-specific + global). Omit to show all.

TDQS

A3.5/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It mentions 'masked values' implying read-only, but does not explicitly state idempotency, authentication needs, or rate limits. Adequate but lacks explicit behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with two clear parts. No wasted words, front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers basic functionality but does not specify return format, pagination, or limits. Given no output schema, more detail would help. Also not differentiated from vault_list_files beyond 'credentials' vs 'files'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'project', which already explains filtering behavior. The description's mention of 'Optionally filter by project' adds no new meaning beyond the schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists stored credentials with masked values, and optionally filters by project. The verb 'list' and resource 'credentials' are specific, and it is distinguishable from sibling tools like vault_delete or vault_store.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives. Sibling tools like vault_list_files also list, but description does not clarify when to use one over the other. No exclusions or when-not scenarios are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_list_filesB

List all stored auth files (metadata only). Optionally filter by project.

ParametersJSON Schema

Name	Required	Description	Default
`project`	No	Filter by project (shows project-specific + global). Omit to show all.

TDQS

B3.1/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must carry the burden. It only reveals 'metadata only' (not file contents) but lacks disclosure on read vs destructive nature, permissions, or side effects. Minimal behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence with the primary purpose front-loaded and no extraneous words. Every part is necessary and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one optional parameter and no output schema, the description is adequate but lacks detail on what metadata fields are returned or how to use results. More context would help distinguish from 'vault_list'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter, which already explains its behavior. The description ('Optionally filter by project') adds no new meaning beyond the schema, so baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all stored auth files (metadata only)' with a specific verb (List) and resource (auth files). It distinguishes from siblings like 'vault_list' by specifying files vs vaults/collections, though not explicitly. The option to filter by project is included.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description only mentions 'Optionally filter by project' as usage guidance. It does not specify when to use this tool versus alternatives like 'vault_list' or when not to use it. No exclusions or context for choosing between tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_storeB

Store an API key in the encrypted credential vault. Upserts by (provider, keyName, project).

ParametersJSON Schema

Name	Required	Description
`apiKey`	Yes	The API key to store
`keyName`	No	Key slot name (default: "default")
`project`	No	Project scope (default: "_global" — shared by all projects)
`provider`	Yes	Provider identifier (e.g. "anthropic", "openai", "google", "groq", "openrouter", "cerebras", "zai", "nvidia", "mistral", "sambanova", "hyperbolic")

TDQS

B3.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description reveals the upsert behavior (create or update) which is a key behavioral trait. However, without annotations, it does not cover error conditions, permissions, or side effects. The burden is partially met but could be more thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that conveys the tool's core purpose and key behavior (upsert) without any filler or redundancy. Every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the parameter count (4) and lack of output schema or annotations, the description provides the essential functionality but omits details about return values, success/error handling, and any prerequisites. It is adequate but minimal.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all parameters (100% coverage), so the base score is 3. The description adds context about the composite upsert key (provider, keyName, project), but does not substantially enhance understanding beyond the schema definitions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's purpose: storing an API key in an encrypted vault, with an upsert behavior based on provider, keyName, and project. It distinguishes from sibling vault tools like vault_delete and vault_list, though not explicitly from vault_store_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide guidance on when to use this tool versus alternatives such as vault_store_file or vault_list. It lacks any 'when to use' or 'when not to use' direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_store_fileA

Store an auth file (e.g. auth.json) in the encrypted vault. Upserts by (provider, fileName, project).

ParametersJSON Schema

Name	Required	Description
`content`	Yes	File content as a string
`project`	No	Project scope (default: "_global" — shared by all projects)
`fileName`	Yes	File name (e.g. "auth.json")
`provider`	Yes	Provider identifier (e.g. "opencode")

TDQS

A3.9/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

States 'encrypted vault' and 'upserts', but no annotations provided. Missing details like size limits, encoding, return value, or permissions required for a write operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, first verb-purpose, second upsert key. No filler, front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, so description should hint at return behavior. It does not mention success/failure indicators. Otherwise covers essential purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% giving baseline 3. Description adds the upsert key combination (provider, fileName, project), which is not in schema descriptions, enhancing parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clear verb 'store' with specific resource 'auth file' and example auth.json. Mentions 'Upserts by (provider, fileName, project)' differentiating it from siblings like vault_store (likely more general) and vault_delete_file.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage: for persisting auth files with upsert semantics. No explicit when-to-use, when-not-to-use, or alternatives among siblings like vault_store.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

30 tool updatesv0.6.0Jul 15, 2026
- First observedapproval_approve
- First observedapproval_deny
- First observedapproval_list
- First observedcircuit_breaker_stats
- First observedcode_search
- First observedconfigure_circuit_breaker
- First observedconversation_check_compaction
- First observedconversation_context
- First observedconversation_find_relevant
- First observedconversation_get_page
- First observedconversation_info
- First observedconversation_navigate
- First observedconversation_paginate
- First observedcreate_group
- First observeddelete_group
- First observeddiscover_models
- First observedindex_codebase
- First observedlist_groups
- First observedllm_generate
- First observedllm_models
- First observedlocal_llm_generate
- First observedshared_state
- First observedusage_query
- First observedusage_summary
- First observedvault_delete
- First observedvault_delete_file
- First observedvault_list
- First observedvault_list_files
- First observedvault_store
- First observedvault_store_file

Deploy Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0

Scored 2026-07-15 05:00 across 30 tools

Disambiguation5/5

Each tool has a clearly distinct purpose due to domain-specific prefixes and action verbs. Overlaps like llm_generate and local_llm_generate are well-differentiated by descriptions indicating local vs. cloud routing.

Naming Consistency5/5

All tools follow a consistent snake_case pattern with a domain prefix (e.g., vault_, conversation_) followed by a verb_noun combination. No mixing of conventions or ambiguous names.

Tool Count4/5

30 tools is on the higher side but each domain (approval, circuit breakers, code search, conversation, groups, LLM generation, shared state, usage, vault) has a reasonable number of tools. The count reflects the server's broad scope without excessive bloat.

Completeness4/5

Most domains have adequate CRUD coverage (e.g., vault store/list/delete, conversation pagination, usage query/summary). Minor gaps exist (no group update, no approval request creation), but core workflows are supported.

Maintenance

ActivityActive

ResponsivenessSlow

Resources

Need Help?

Related Servers

Related MCP Connectors

nexusOAuth
com.civic
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Agent Orchestration Developer Tools App Automation
2
OneDroid SynapseOAuth
ai.onedroid
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
Security Observability
1
SandBase
io.github.sandbaseai
Connect MCP clients to 2,000+ AI models without managing provider API keys.
AI & Machine Learning Agent Orchestration
1116
toolweaveOAuth
io.github.andreysparish
One MCP endpoint for Claude, GPT & Gemini: 100+ tools + no-code connectors + agent workers.
App Automation AI & Machine Learning Agent Orchestration
2

Related MCP Servers

Proxima
AI & Machine Learning Developer Tools
Zen4-bit
F
license
Not graded
quality
A
maintenance
A local AI gateway that connects multiple AI providers (ChatGPT, Claude, Gemini, Perplexity) to your development environment via MCP tools, enabling coding, search, analysis, and more without API keys.
Updated a month ago (2026-08-17 17:16 UTC)
17
1,171
-
MCP-AI-Gateway
AI & Machine Learning Observability
YoushaaMurhij
F
license
Not graded
quality
D
maintenance
Unified local MCP AI Gateway that routes across Groq, OpenRouter, Mistral, and local Ollama providers, with OpenAI-compatible APIs, MCP tools, fallback/racing router, monitoring, and web dashboard.
Updated 6 months ago (2026-03-09 16:57 UTC)
-
Adaptive LLM Gateway
AI & Machine Learning Security Agent Orchestration
renefichtmueller
A
license
Not graded
quality
B
maintenance
Exposes an OpenAI- and Anthropic-compatible HTTP, SSE, and stdio gateway that wraps multiple subscription CLIs, adding prompt-injection defense, PII redaction, cost-aware routing, and reasoning-trace capture for MCP-compatible clients like Claude Desktop and Cursor.
Updated 2 days ago (2026-09-11 08:53 UTC)
4
11
Apache 2.0
Toolport
Agent Orchestration Developer Tools Security
btsouth
A
license
A
quality
A
maintenance
One local gateway for all your MCP servers — shared by every AI coding tool (Claude, Cursor, VS Code, Codex). Set up each server once; keys stay in the OS keychain; lazy discovery keeps agent context small. Local-first, open source.
Updated 2 days ago (2026-09-11 01:29 UTC)
4
130
211
MIT

MCP LLM Bridge

Demo Links

Quick Portfolio Snapshot

Why It Matters

Quick Start

Jump to Technical Docs

Technical README

Table of Contents

Quick Start

Dashboard

First-Time Setup

Local Inline Shell Capabilities

React Admin App Capabilities

API Reference

Core HTTP Endpoints

POST /v1/generate

POST /v1/chat/completions

GET /v1/models

GET /v1/providers

Credentials API

Auth Files API

Usage, Cost, Metrics, and Health

Provider Groups

Providers

API Providers

CLI Providers

OpenCode Model Coverage

Provider Priority and Fallback

Authentication

Bearer Token

Auth Rules

Project Scoping

Credential Management

Global vs Project Credentials

API Keys

Auth Files

Claude and OpenCode Credential Sync Pattern

Cross-Model Bridge

Supported Task Types

Example bridge.yaml

Bridge Response Metadata

Context Compression

Strategies

Usage

Operational Characteristics

Semantic Code Search

Supported Languages

MCP Search Tools

Search Modes

Embedding Model

Environment Variables

CRDT Multi-Agent State

Supported CRDTs

Example Operations

Integrations

OpenCode

GHAGGA

Any OpenAI-Compatible Tool

Docker Deployment

Docker Compose

Docker Build and Run

What the Image Includes

Coolify

MCP Server

Primary MCP Tools

PageIndex Conversation Tools

Claude Code Config

Claude Desktop Config

Dynamic MCP Servers

What It Is

Enable

Create a Plugin

Directory

Security

Coexistence with Static Tools

Configuration

Core Environment Variables

Optional Runtime Features

Master Key Priority

Bridge Config Path

`POST /v1/generate`

`POST /v1/chat/completions`

`GET /v1/models`

`GET /v1/providers`

Example `bridge.yaml`