Agent Discoverability Foundation — Fix the Front Door

2026-03-25

apimcpsdk-tssdk-pyintelligence

What We Built

BrainstormRouter has 13 intelligence systems, 66 MCP tools, Thompson sampling, semantic cache, memory, guardrails, agent profiles, forensics, and budget systems. Agents couldn't discover any of it.

This phase fixes the front door:

/v1/self enriched with discovery links to every endpoint, intelligence system status (13 systems), MCP tool count, and a bootstrap path for new agents.
/v1/discovery enriched with full MCP tool listing — every tool by name, description, permission, and category (replacing the old count-only tools: 65).
POST /v1/onboard created — one-call agent setup that returns recommended models, relevant MCP tools, configuration, budget, and personalized first-steps based on preferred tasks.
First-request welcome — new API keys receive X-BR-Welcome headers on their first completion request pointing to /v1/self, /v1/discovery, and /v1/onboard.
Intelligence headers on all completions — X-BR-Complexity-Level, X-BR-Complexity-Score, X-BR-Models-Considered, and X-BR-Selection-Confidence now set on every response, including explicit model requests (previously only set for auto-selection).

Why It Matters

Every AI agent hitting BrainstormRouter for the first time was blind. The Brainstorm CLI treated BR as a dumb proxy for weeks because it couldn't discover the intelligence systems. Now agents discover everything in one call.

How It Works

# One call to discover everything
curl -H "Authorization: Bearer $KEY" https://api.brainstormrouter.com/v1/onboard \
  -d '{"preferred_tasks": ["code"], "budget_hint": "moderate"}'

# Response includes recommended models, relevant tools, config, budget, first steps

Intelligence headers on every response:

X-BR-Selection-Method: thompson-sampling
X-BR-Complexity-Level: moderate
X-BR-Complexity-Score: 4
X-BR-Models-Considered: 12
X-BR-Selection-Confidence: 0.87

Lockstep Checklist

[x] API Routes: src/api/routes/self.ts, discovery.ts, onboard.ts, completions.ts updated.
[x] TS SDK: packages/sdk-ts — Onboard resource + updated SelfResponse type.
[x] Python SDK: packages/sdk-py — Onboard + AsyncOnboard resources.
[x] MCP Schemas: br_onboard tool added to manifest and server.
[ ] Master Record: Pending update.