ask is the one tool ask-kit gives an agent. This page lists its parameters, the text it returns
and when it reports an error. For how it works inside, see
The life of an ask.
Source: src/router.mjs
(serveRouter), src/ask.mjs
(registerAsk) and src/server.mjs.
The router and the domain servers
ask-kit serve starts the MCP server an agent registers. It has two forms:
| Command | Server name | What the agent sees |
|---|---|---|
ask-kit serve |
ask |
The router’s ask. It picks a domain, starts that domain’s server on first use and forwards the call. This is what setup registers. |
ask-kit serve --domain <name> |
ask-<name> |
That domain’s own ask, with no routing. ask-kit ask --domain and the benchmark use this form. |
An agent gets one tool in either case. The investigator’s own server, which has the REPL tools,
is started with ASK_KIT_INNER=1 and never shows ask. See
The REPL.
Both forms need a config file. Without one the server exits at start with
ask-kit is not set up yet, and the agent lists no ask tool.
Parameters of the router’s ask
| Parameter | Type | Required | What it does |
|---|---|---|---|
question |
string | yes | The question or request in plain words, with any ids, names or dates you know. |
about |
one of the enabled domain names | no | Which investigator answers. Left out, the router chooses. |
continue |
boolean | no, default false |
Send this as a follow-up to the investigator that answered your last question. |
backend |
string | no | A backend name from the config. Left out, the domain’s backend is used. |
timeoutSeconds |
integer, 30 to 900 | no | How long the investigation may run. The domain’s ask defaults to 300. |
The tool’s description lists the enabled domains with their one-line descriptions (the says
field of each domain), and the server’s instructions repeat them.
How the router chooses a domain
In this order, first match wins:
how |
When |
|---|---|
caller |
about was given. |
follow-up |
continue is true and an earlier ask from this caller exists. It goes to the domain that answered last. |
only |
One domain is enabled. |
model |
router.backend is set and its one-word answer names an enabled domain. |
rules |
The model call failed or said something else, or no router model is set. Keyword rules. |
The router remembers the last domain per calling session on disk, so a follow-up from a new process (the shell, a restarted agent) still reaches the same investigator.
The router passes continue: true on to the domain only when the chosen domain is the one that
answered last. If you give about: "code" with continue: true after a sessions answer, the
call runs as a new question on code.
Router limits
- The router waits
timeoutSeconds(300 when left out) plus 30 seconds for the domain’s reply. backendis checked by the domain’s server, not the router. An unknown name comes back as an error from the domain (see below).
Parameters of a domain’s ask
| Parameter | Type | Required | What it does |
|---|---|---|---|
question |
string | one of the three | The question or request. |
request |
string | one of the three | Same as question. |
prompt |
string | one of the three | Same as question. |
backend |
one of the backend names in the config | no | The model that investigates. Default: see backends. |
continue |
boolean | no, default false |
Ask the same investigator as your last question on this backend, so it keeps what it found. |
timeoutSeconds |
integer, 30 to 900 | no, default 300 | Time limit for the ask. |
If several of question, request and prompt are given, the first non-blank one in that order
is used. The tool’s description is the domain’s askDescription, followed by
For a follow-up, pass continue: true ... and the list of backend names with the default.
How long an ask may run
The time limit is the smaller of timeoutSeconds and the calling agent’s own tool timeout minus
15 seconds, and never under 20 seconds. ask-kit reads that tool timeout, in milliseconds, from
the environment variable MCP_TOOL_TIMEOUT when the agent sets it. This keeps the answer from
arriving after the agent has already dropped the call.
For an api backend the investigation stops at the limit, or after 20 steps, and the model gets
one more call to say what it found. For the agent CLIs the limit is the process timeout, with
13 seconds added for the CLI to finish.
Follow-ups
continue: true goes back to the last investigator ask-kit ran for this calling session on the
same backend. The caller’s session is the first of these environment variables that is set:
ASK_KIT_SESSION, CLAUDE_CODE_SESSION_ID, CODEX_THREAD_ID, CODEX_SESSION_ID,
COPILOT_SESSION_ID. If none is set, ask-kit uses client-<pid of the agent process>.
A follow-up needs an earlier question on the same backend. Without one it fails with
nothing to continue: no earlier <backend> question in this session.
What comes back
A successful ask returns one text block: the answer, then a blank line, then a footer.
Exporters implement Exporter in src/export/base.ts:12 ...
[code · glm-5.3-flash · 21s · $0.0031]
(An illustration of the shape; the text is the investigator’s own.)
The footer is [<domain> · <backend> · <seconds>s · $<cost>].
| Part | Meaning |
|---|---|
<domain> |
The domain that answered. |
<backend> |
The backend’s name from the config. |
<seconds> |
Time of this ask, rounded. For claude-cli and codex-cli it leaves out the warm-up. |
· $<cost> |
Four decimals. Shown only when the cost is known and above zero: OpenRouter backends and claude-cli. Not shown for Codex, Copilot CLI and other APIs. |
The router adds a last line when it chose the domain itself:
[routed to code by model]
The word after by is model, rules or follow-up. Nothing is added when you gave about
or when one domain is enabled.
Notes the answer can carry
When an api investigation did not finish, the answer says so in its text. These notes are part
of the answer, and isError stays false.
| Text | Meaning |
|---|---|
[stopped at the 20-step limit; this is what it found] or [stopped at the <N>s time limit; ...] |
It ran out of steps or time and was asked for what it had. |
[stopped at ... after <N> cells, with nothing it could report] |
It ran out and the closing call returned nothing. |
[the reply hit the length limit and may be cut off] |
The model’s reply was cut at max_tokens. |
[not finished: ask again with continue: true to carry on from here] |
Added to every partial answer. |
[answered at the step limit: if something is missing, ask again with continue: true] |
It answered with two or fewer steps left. |
Errors
An error has isError: true and text starting ask failed (<backend>): <message>. Through the
router the text is ask failed (<domain>): <message>.
| Message | Cause |
|---|---|
ask needs `question`: the question or request, in plain words. |
None of question, request, prompt held text. No ask failed prefix. |
nothing to continue: no earlier <backend> question in this session |
continue: true with no earlier ask on that backend. |
no API key for <provider>: {...} is empty |
An api backend found no key. See Key references. |
backend has no baseUrl (preset <name>) |
An api backend with no base URL. |
<preset> <status>: <body> |
The provider returned an HTTP error or an error body. |
warming failed: ... |
The agent CLI could not start its warm session. |
claude exited <code>: ..., codex exited ..., copilot exited ... |
The CLI exited without a result. Often it is not signed in. |
the calling client cancelled the ask |
The agent cancelled the call. Also journaled as cancelled. |
backend <name> has unknown kind "<kind>" |
A kind that is not one of the four. |
Two more cases return text with isError: true and no ask failed prefix: a claude-cli result
the CLI marked as an error returns that text, and a codex-cli run that produced no message
returns codex failed: ... or an empty answer.
A backend name that is not in the config is rejected before the ask runs, by the MCP schema of
the domain’s server, and the agent gets the client library’s validation message.
Every ask, failed or not, is written to the journal.
Progress
A caller that sends a progressToken (the MCP client’s onprogress) gets one
notifications/progress per cell while an API backend works: progress is the cell’s number and
message is cell <n>: <first line>, the cell’s leading comment if it has one, cut at 100
characters. The router passes them on from the domain’s server. CLI backends (Claude Code, Codex,
Copilot) send none.
From the shell
ask-kit ask "<question>" [--domain <name>] [--backend <name>] [--continue]
Starts ask-kit serve (with --domain when given) as a child, calls ask with a 900 second
client timeout, prints the text and exits with code 1 on isError. It asks for progress: on a
terminal, stderr shows a spinner with the seconds so far and one line per progress note; piped,
the notes are plain lines. On a terminal (and without NO_COLOR) the answer’s Markdown is
rendered: headings and bold in bold, code in colour, bullets as •, the footer dimmed. Piped
output is the answer text unchanged. The shell is its own caller:
its session is ASK_KIT_SESSION or shell-<pid of the shell>, so --continue works between
shell commands in the same shell. With no --domain it goes through the router.
Related: Command line, Use it.