---
title: "The `ask` tool reference"
url: https://temet.ai/docs/ask-kit/reference/ask-tool/
modified: 2026-11-19
summary: "ask is the one tool ask-kit gives an agent."
---

# The `ask` tool reference

`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](https://temet.ai/docs/ask-kit/internals/ask-lifecycle/).

Source: [`src/router.mjs`](https://github.com/temet-ai/ask-kit/blob/main/src/router.mjs)
(`serveRouter`), [`src/ask.mjs`](https://github.com/temet-ai/ask-kit/blob/main/src/ask.mjs)
(`registerAsk`) and [`src/server.mjs`](https://github.com/temet-ai/ask-kit/blob/main/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](https://temet.ai/docs/ask-kit/internals/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.
- `backend` is 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`](https://temet.ai/docs/ask-kit/reference/config/#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](https://temet.ai/docs/ask-kit/reference/config/#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](https://temet.ai/docs/ask-kit/reference/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

```sh
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](https://temet.ai/docs/ask-kit/command-line/), [Use it](https://temet.ai/docs/ask-kit/asking/).
