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

# Tool commands

> Commands AI agents use to discover, price, and call tools.

All tool commands require authentication. An AI agent should discover a tool, inspect its contract and price, and only then call it.

## List and search

```bash theme={null}
cralo tools list [--cursor <cursor>]
cralo tools search <query> [--cursor <cursor>] [--limit <n>]
```

## Describe and quote

```bash theme={null}
cralo tools describe <tool> [--version <version>]
cralo tools quote <tool> --input <json|@file|-> [--version <version>]
```

Agents should treat description output as the canonical source for the current input schema, output schema, price, version, and limits.

## Call

```bash theme={null}
cralo tools call <tool> \
  --input <json|@file|-> \
  [--version <version>] \
  [--max-price <usd>] \
  [--idempotency-key <key>] \
  [--async] \
  [--timeout <duration>]
```

| Option              | Meaning                                                                                                            |
| ------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `--input`           | Required JSON input: inline, `@file`, or `-` for stdin.                                                            |
| `--version`         | Pin a semantic tool version.                                                                                       |
| `--max-price`       | Maximum approved price in USD.                                                                                     |
| `--idempotency-key` | Use only for controlled recovery of the exact same call.                                                           |
| `--async`           | Skip client-side waiting and return the admission response as-is. Available on queued-execution tools (see below). |
| `--timeout`         | Client wait duration, such as `300s`. Has no effect with `--async`.                                                |

The CLI generates an idempotency key by default and applies a quote-based price guard before admitting an agent's paid call.

`--async` is available on tools whose `cralo tools describe <tool>` output includes `execution_class: "queued"` (currently `video.transcript`, `perplexity.research`, `instagram.posts`). Check `meta.status` in the response and poll `cralo invocations get <id>` when it is `queued` or `running`. Passing `--async` to any other tool is rejected with `ASYNC_NOT_SUPPORTED`.