> ## Documentation Index
> Fetch the complete documentation index at: https://graph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ask

> Asks the person running the plan a question and uses their answer.

## When to use it

* For a value only the person running the plan knows, or a confirmation before an irreversible action.
* Not for anything a tool can look up or a gate can judge.

## How it works

* `outputSchema` must be a flat object of strings, numbers, booleans and enums.
* The terminal, the workbench and MCP clients each show the question their own way.
* `whenUnanswered` decides what happens when nobody can answer, such as in CI: `fail` (the default) or `default`, which uses `default`.

## Input

**default** `any`

The fallback answer used when whenUnanswered is 'default', and the answer a host offers prefilled. Must conform to outputSchema. May use templates.

**outputSchema** `any` *required*

JSON Schema for the answer. Must be type object whose properties are all primitives (string, number, integer, boolean) or string enums — no nested objects or arrays. Give every property a description written as a question: it is what the user reads for that field. May be a template (\{\{E1.schema}}) or contain templates (an enum from \{\{E1.names}}); it is then checked when the step runs.

**prompt** `string` *required*

The question, as the user will see it. May use templates like \{\{E0.candidates}}.

**whenUnanswered** `enum\<string\>`

What to do when nobody can answer (headless run, client without elicitation support, user declined). 'fail' (the default) fails the step; 'default' falls back to the `default` value.

Available options: `fail`, `default`

## Result

Later steps read these as `{{<step id>.<field>}}`.

**answer** `object`

The answer, matching `outputSchema`.

**answer.repo** `string`

**answered** `boolean`

False when the person declined or nobody could be asked.

**reason** `string`

When `answered` is false: `declined` or `unavailable`.

```yaml Plan step theme={null}
- id: E1
  tool_name: ask
  input:
    prompt: "{{input.prompt}}"
    outputSchema: "{{input.outputSchema}}"
```

```json Result theme={null}
{
  "answer": {
    "repo": "tylerdavis/graph"
  },
  "answered": false,
  "reason": "unavailable"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.