1. The Limits of a Single Model
No single model is best at every step of an engineering task. Providers differ in what they are tuned for and in what they can reach. In broad strokes, and subject to change with each release:
- Perplexity is built around live web search with citations, which suits questions about current libraries and recent changes.
- Claude is widely used for careful coding, refactoring and long-form reasoning.
- ChatGPT covers a wide range of general knowledge and quick transformations.
- Gemini offers large context windows and engines of different speed and depth (
flash,pro).
Because the models available to you depend on your accounts and change often, treat those strengths as starting assumptions and check them against your own prompts. The point of orchestration is not to trust a ranking. It is to get a second opinion cheaply, to separate research from writing from review, and to catch the mistakes that one model tends to repeat.
2. Core Orchestration Primitives in Proxima
Multi-model behavior is exposed through a handful of MCP tools. They live in
src/mcp/tools-workflow.js, tools-content.js and tools-chat.js:
| Tool | Source module | What it does |
|---|---|---|
smart_query |
tools-chat.js |
One entry point with four modes: auto (a single well-chosen provider), verify (a primary answer plus a cross-model check), consensus (all providers answer and vote) and collaborate (role-based teamwork). The reply ends with a footer naming the strategy, providers, a quality score and the time taken. |
run_workflow |
tools-workflow.js |
An ordered list of steps in which each step's output feeds the next. A step can name a provider or leave it empty to be auto-routed. |
run_loop |
tools-workflow.js |
Iterates one task: generate, have another AI review, improve, until it converges or reaches maxTurns (default 3). The reviewer defaults to Claude. |
crew |
tools-workflow.js |
A role-based pipeline. The default is Researcher (Perplexity), Writer (Claude), Reviewer (ChatGPT), each receiving the previous role's output. |
debate |
tools-content.js |
Assigns different stances to different providers and collects their arguments in parallel. |
verify |
tools-content.js |
Asks several providers the same question or claim and asks each for an answer, a confidence percentage and caveats. |
ask_all_ais |
tools-chat.js |
Sends the same message to every enabled provider in parallel and returns each answer side by side. |
proxima_cost_report |
tools-workflow.js |
Reports this session's requests and tokens per provider, and the estimated money saved compared with paid API usage. |
All of these use whichever providers you have enabled. With only one provider enabled, debate
falls back to asking that one model to argue several perspectives, and the other tools run on it too.
3. Sequential Chaining (run_workflow)
A chain suits work with distinct phases. In src/mcp/tools-workflow.js,
run_workflow hands an array of steps to the workflow engine, which runs them in order and
passes each step's response to the next as context. This is the registration, abridged:
server.registerTool('run_workflow', {
title: 'Run Workflow (sequential)',
inputSchema: {
steps: z.array(z.object({
task: z.string().describe('What this step should do'),
provider: z.string().optional().describe('Which AI to use (auto-routed if empty)'),
})),
name: z.string().optional(),
input: z.string().optional().describe('Initial context/input for first step'),
},
}, async ({ steps, name, input }) => {
const result = await workflowEngine.execute({
name: name || 'MCP Workflow', steps, input: input || '',
chatFn: agenticChatFn, enabledProviders: getEnabledProviders(),
});
return toolResponse({
status: result.status,
finalOutput: result.finalOutput,
summary: result.summary,
steps: result.steps.map(s => ({ step: s.step, provider: s.provider,
autoRouted: s.autoRouted || false, elapsedSec: s.elapsedSec, error: s.error || null })),
});
});
A typical call from an editor, with providers chosen to fit each phase:
{
"name": "Add a rate limiter",
"input": "Express API, Node 20, TypeScript",
"steps": [
{ "task": "List the current best-practice libraries for rate limiting in Express and any recent breaking changes", "provider": "perplexity" },
{ "task": "Using that research, write the middleware and its types", "provider": "claude" },
{ "task": "Review the code for edge cases and write tests", "provider": "chatgpt" }
]
}
4. Role-Based Crews (crew)
A crew is a chain in which every step has a role. Each role gets a prompt of the form "you are a
<role>", its own instruction, the original task, and the previous role's output. With no arguments,
crew runs Researcher on Perplexity, Writer on Claude and Reviewer on ChatGPT. You can pass
your own list:
{
"task": "Design a high-throughput WebSocket ingestion service in Node.js",
"agents": [
{ "role": "Researcher", "provider": "perplexity", "instruction": "Compare ws with other Node WebSocket libraries and note current benchmarks." },
{ "role": "Architect", "provider": "claude", "instruction": "Propose the design: backpressure, batching, failure handling." },
{ "role": "Reviewer", "provider": "chatgpt", "instruction": "Find security and performance problems in the design." }
]
}
If you name a provider that is not enabled, the step is routed automatically and the output says which provider was unavailable. Crew roles run one after another, so the total time is the sum of the steps.
5. Debate, Verification and Consensus
A model tends to agree with the framing of the prompt it is given. Three tools push against that:
Debate (debate)
The tool assigns each provider a stance (for, against, neutral, alternative), tells it to argue only that
side, and sends all of the requests in parallel. You get back each provider's strongest case, which makes
the trade-offs visible. It is a single round, not a back-and-forth, and there is no judge model: you read
the results and decide. The sides argument sets how many perspectives to gather (default 2).
Cross-checking a claim (verify)
verify asks one or more providers the same question and requires each to answer in a fixed
format: ANSWER, CONFIDENCE (0 to 100 percent) and CAVEATS. Placing the
answers side by side is what makes disagreements obvious. It checks facts and reasoning. It is not a
static analyzer, so for code use security_audit or review_code.
Consensus and verify modes (smart_query)
In verify mode, smart_query gets a primary answer and then has a second model
check it. In consensus mode, all enabled providers answer and the results are combined. Use
these when the cost of a wrong answer is higher than the cost of a few extra requests.
6. Token Tracking and Cost Observability
Several providers per request means several times the usage, so it is worth seeing the numbers. The
proxima_cost_report tool is read-only and returns a text summary for the current session:
total requests, total tokens, the estimated amount saved compared with paying per token for the same usage,
and a per-provider line with requests and tokens.
Proxima Cost Report
====================
Total Requests: <n>
Total Tokens: <n>
Money Saved: <estimate>
...
Per Provider:
perplexity: <n> requests, <n> tokens
claude: <n> requests, <n> tokens
chatgpt: <n> requests, <n> tokens
The "saved" figure is an estimate. In Session Mode you pay nothing per token, so it shows what the same
usage would have cost through paid APIs. For a broader health view, proxima_agentic_status
reports the current mode, provider health from the smart router, memory, run-loop statistics and cost.
7. Diagnostic Failure Analysis
| Symptom | Cause | Diagnosis | Fix |
|---|---|---|---|
| A step fails or returns nothing | That provider's session expired, it was rate-limited, or the named model is not available on your account. | Call ask_model for that provider alone. Run list_available_models to see what is available. |
Log in again, pick another provider for the step, or leave provider empty so the step is auto-routed. |
| Quality drops along the chain | A later step did not receive a constraint that was only stated at the start. | Compare the responsePreview of each step in the result. |
Repeat essential constraints in every step's task, or put them in input. |
debate returns one model arguing several sides |
Only one provider is enabled. | Check the enabled providers in the Proxima app. | Log in to a second provider, or accept the single-model perspectives. |
| Requests run slowly | Steps in a chain and roles in a crew run one after another, and each provider call waits in a per-provider queue. | Check elapsedSec for each step in the result. |
Use ask_all_ais or verify for work that can run in parallel, and keep chains short. |
8. Architectural Takeaways
Chains separate research, writing and review. Crews add roles to that. Debate and verification expose disagreement instead of hiding it, and the cost report keeps the extra requests visible. None of these guarantee a correct answer, but together they make a wrong one easier to notice before it reaches your code.