How the orchestrator picks tools

You do not have to name tools. Type what you want to know — "what shape is this protein and where could a drug bind?" — and the orchestrator infers the capability, selects the tools that provide it, and chains them in order. This page walks the path from your message to the canvas cards, so you know when to trust the inference, when to be explicit, and what the platform does when a step is ambiguous or a tool fails.

The one idea to hold onto: the orchestrator routes on the capability your goal implies, not on tool names. A capability is a concrete scientific operation — "predict a 3D structure," "search compounds by activity," "plan a synthesis" — and most capabilities are served by more than one interchangeable tool. You ask for the outcome; the orchestrator picks the tool.

The path from message to result

Five things happen between your message and the cards. You see the results of every step; the routing itself runs in the background.

1. It reads your goal. The orchestrator classifies what you want and picks out any identifiers you supplied — a SMILES string, a UniProt ID, a PDB code, a gene symbol. If you name a tool directly ("use AlphaFold"), that naming is honored and skips the inference.
2. It maps the goal to a capability. A verb like "fold," "dock," "compare," or "make" implies a class of operation; a noun like "pocket," "off-target," or "route" narrows it; the identifiers you provided confirm it. That capability resolves to a set of relevant tools.
3. It loads only the relevant tools. The tools that serve your capability become available for this turn; unrelated tools stay out of scope. This is why Ivy does not wander off into unrelated analyses — and why it will not call a tool that does not exist.
4. It runs the chain. Ivy calls the tools in order, passing each tool's structured output into the next tool's input, so a single request becomes one chained run rather than a to-do list.
5. It grounds the answer. Before the final answer reaches you, the platform checks that every claim traces to a tool that actually ran (see Grounding below).

From intent to tool chain

The orchestrator infers the capability first, then assembles the chain that carries you from what you have to what you asked for. None of the requests below name a tool.

The same routing runs whether you phrase a goal naturally or name the tools yourself — naming them just skips the inference. To see the capability-to-tool map behind these choices, read What you can achieve; for a goal-to-tool lookup, Which tool?.

Why capabilities, not tools

Most goals are served by several tools that do roughly the same thing and differ only in speed, coverage, or the input they accept — AlphaFold fetches a known structure in seconds while ESMFold predicts a novel one; ADMET-AI runs a fast broad panel while ADMETLab3 runs a wider endpoint set. Keying on the capability lets the orchestrator pick the tool that fits your case, and lets it fall back to an interchangeable one when the first is unavailable.

Each tool also carries documented alternatives. If a tool fails or returns nothing, Ivy can switch to another tool that provides the same capability rather than stopping — a compound search that comes up empty on one database is retried on another. This is a routing decision Ivy makes and shows you, not a silent infrastructure swap.

Why chaining is automatic

Most questions in discovery are multi-step: you rarely want a structure without also wanting to know where a molecule binds it, or a generated molecule without knowing whether it is synthesizable. Because each tool returns structured output, the orchestrator can feed one tool's result straight into the next tool's input — a predicted structure becomes the docking target; a docked pose becomes the input to rescoring. After a tool completes, Ivy often suggests the natural next step.

Most links in the chain are Ivy's choice for your request: a predicted structure becomes the docking target because your goal implied docking. A few follow-ups start on their own once a step finishes, run in the background, and appear as their own cards:

• molecules from GenMol are screened through ADMET-AI;
• the top three compounds from an ADMET-AI run get a retrosynthesis route from AiZynthFinder;
• a route's starting materials are checked against ZINC for commercial availability.

This replaces the fixed "Smart" workflows (Smart Structure, Smart Docking, Smart ADMET, Smart XRD) that earlier versions of these docs described. Each of those ran one preset pipeline with default settings. The orchestrator now builds the chain from your request, so the same goals are served by describing them, and you can change any step by naming a tool or a parameter.

When to be explicit

Let the orchestrator choose when you are exploring or do not care about exact parameters. Name tools and parameters when you need control:

• Pin a specific tool when two tools provide the same capability and you want one — "use AlphaFold, not ESMFold."
• Set parameters when defaults do not fit — a Tanimoto threshold, a docking box, a confidence cutoff.
• Inspect intermediates when you want to check a step before continuing — ask for one tool at a time instead of the whole chain. See Decisions.

When inference is uncertain

The orchestrator resolves what it safely can and asks when it cannot. If your message names only an entity with no action — "KRAS" on its own — or an expensive prediction job is missing a parameter it truly needs, Ivy asks a clarifying question rather than guessing. When the action is clear even if the scope is open ("fold this sequence"), it acts and asks about the downstream step afterward. Cheap context — resolving "aspirin" to its structure, looking up a UniProt entry — it fills in quietly so you do not have to.

Grounding: what keeps the answer honest

The final answer is checked against what the tools actually returned. If Ivy's draft narrates a result from a tool that failed or was never called, reports more rows than a tool produced, or invents a specific value with no tool behind it, the platform removes that claim before you see it and keeps the grounded analysis. A tool failure is surfaced as a failure, not papered over — and Ivy does not invent a sequence, a SMILES string, or a data value to fill a missing input.

Every step surfaces as its own canvas card, so you can always see exactly which tools ran, in what order, and on what inputs.

What the chain leaves behind

Each step is also a row in the run's record: tool calls and job events are written to a hash-chained log, one chain per chat or session. Signed in, runs from the web app, the terminal, curl or MCP leave a tamper-evident record you can check — edit a row and the chain breaks at the verifier. It detects modification; it does not prevent it, and it is not access control.

• To check a chat from the web app or the terminal, call GET /audit/chat-chain/{chatId} as its owner. A chat that continues guest chats you claimed at sign-up checks those too.
• To check a curl or MCP run, call GET /audit/session-chain/{sessionId} as its owner. Every signed-in POST /orchestrate response carries this link as record.verify.api.
• Either way, a broken chain comes back as a normal response with status set to broken, naming where it stops matching.
• Guest chats in the browser are written to the record too. Guests cannot check them from these pages yet.
• Calls without an account (curl or MCP with no key) write nothing that lasts.

Read next