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

# Tools and agent tasks

> Discover and call Custory tools from the CLI.

Use this page when you want to inspect Custory's available tools or call one directly from the terminal.

## What this is

Custory exposes bounded tools that can read or update workspace and journey context.

The CLI can:

* list available tools
* describe a tool contract
* call a tool with JSON input
* run a higher-level Custory agent task

## List tools

Run:

```bash theme={null}
custory tools list
```

Human-readable output shows each tool name and description.

For scripts:

```bash theme={null}
custory tools list --json
```

## Describe a tool

Run:

```bash theme={null}
custory tools describe custory.list_personas
```

The CLI prints the tool schema as JSON.

For machine-readable output:

```bash theme={null}
custory tools describe custory.list_personas --json
```

Use the schema as the source of truth for the tool's input shape. Avoid guessing tool arguments from prose.

## Call a tool with inline JSON

Use `--input` for small JSON objects:

```bash theme={null}
custory tools call custory.list_personas --input '{}'
```

`--input` is limited to small payloads. Use `--file` or `--stdin` for larger input.

## Call a tool from a file

```bash theme={null}
custory tools call custory.get_journey_state --file ./tool-input.json --json
```

The file must contain a JSON object.

## Call a tool from standard input

```bash theme={null}
printf '%s\n' '{"journeyId":"journey_example"}' | custory tools call custory.get_journey_state --stdin --json
```

Standard input must be valid UTF-8 and valid JSON.

## Partial tool outcomes

Some tools can return a structured result where `success` is `false`.

When that happens, the CLI exits with code `4`. Treat the output as an intentional tool result, not necessarily a crashed CLI process.

Use the returned message and fields to decide whether to retry, fix permissions, narrow scope, or change the input.

## Run an agent task

Use `custory agent run` for a higher-level goal instead of one direct tool call.

```bash theme={null}
custory agent run \
  --workspace "Acme" \
  --goal "Review the onboarding journey and suggest missing friction points." \
  --mode journey
```

You can also scope by journey:

```bash theme={null}
custory agent run \
  --journey journey_example \
  --goal "Improve the persona assumptions for this journey." \
  --mode personas
```

Supported modes are:

* `journey`
* `personas`

If you omit `--mode`, Custory chooses from the available task context.

## Permission and scope failures

If a tool fails because the workspace or journey is not accessible:

1. Run `custory status`.
2. Run `custory workspace list`.
3. Confirm you are using the correct workspace slug, ID, or journey ID.
4. Ask a workspace owner for the required access if needed.

Read-only access is not enough for write tools.

## Next step

Read [Command reference](/cli/reference) for the full command list, or [Coding agents and MCP](/cli/agents-and-mcp) to connect these tools to an MCP client.