Tools and agent tasks

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:

custory tools list

Human-readable output shows each tool name and description. For scripts:

custory tools list --json

Describe a tool

Run:

custory tools describe custory.list_personas

The CLI prints the tool schema as JSON. For machine-readable output:

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:

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

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

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.

custory agent run \
  --workspace "Acme" \
  --goal "Review the onboarding journey and suggest missing friction points." \
  --mode journey

You can also scope by journey:

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:

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

Read-only access is not enough for write tools.

Next step

Read Command reference for the full command list, or Coding agents and MCP to connect these tools to an MCP client.

Start here

Workflows

Reference

What this is

List tools

Describe a tool

Call a tool with inline JSON

Call a tool from a file

Call a tool from standard input

Partial tool outcomes

Run an agent task

Permission and scope failures

Next step

​What this is

​List tools

​Describe a tool

​Call a tool with inline JSON

​Call a tool from a file

​Call a tool from standard input

​Partial tool outcomes

​Run an agent task

​Permission and scope failures

​Next step

What this is

List tools

Describe a tool

Call a tool with inline JSON

Call a tool from a file

Call a tool from standard input

Partial tool outcomes

Run an agent task

Permission and scope failures

Next step