> Documentation index: https://usertold.ai/llms.txt

# For Agents

> Give your agent a direct line to real users.

UserTold gives product and coding agents tools to design studies, make them available in-product, and receive source-linked evidence after real users take part. Agents can inspect that source before deciding what should become work.

[Core Concepts](/docs/concepts) explains Studies, Interviews, Evidence, Findings, and delivery.

## What code context cannot show

Code analysis shows how a product works, not where users struggle or why they abandon a task. UserTold captures that missing context through in-product interviews.

- Why do they abandon checkout?
- What would make them switch to a competitor?
- Does similar evidence appear after you shipped a fix?

## Choose an interface

UserTold.ai exposes the same project-scoped research data through four automation surfaces:

- **UserTold plugin** for guided workflows in ChatGPT and Codex — [install it from the shared plugin directory](https://chatgpt.com/plugins/plugin_asdk_app_6a8759c2dba48191b391f3915cc0ee5f?open_in_app)
- **MCP** for agent-native discovery and orchestration
- **CLI** for shell workflows and non-interactive scripts
- **REST** for direct integrations, with schemas at [/api/openapi](https://usertold.ai/api/openapi)

For any MCP client, paste this prompt:

```agent-prompt
Help me connect UserTold to this agent with https://mcp.usertold.ai/mcp and complete browser authorization.

Call projects.list to find my existing Projects. If I need a new Project, call organizations.list to get its organizationRef. Ask me to select or create a Project, then proceed. Propose changes before acting.
```

MCP provides authorized short-lived native resource links for complete authoritative interview transcripts, recordings, and source artifacts through `interviews.get_artifacts`. Download the returned `transcript_text` resource once for the complete transcript; artifact bytes are not carried in the tool response.

Agents can use the copyable [`usertold-study-design` skill](/.well-known/agent-skills/usertold-study-design/SKILL.md) to choose a complete script before validation and activation.

For discovery without parsing prose, run `usertold --help --json` or add `--json` to a CLI group or subcommand help call. Operations emit structured output with `--json` or `--format json`. MCP clients start with the bounded `usertold://organizations` and `usertold://projects` resources before using project-scoped tools; protocol initialization never returns account identity.

## Pricing

**Managed AI:** $0.25 per recorded minute with inference included; no per-interview minimum; an interview already running finishes even if your balance runs out

Includes: interview orchestration, Evidence extraction, source-linked Finding creation and review, tracker handoff, Linear completion sync, dashboard.

**Use your OpenAI key (BYOK):** $0.15 per recorded minute to UserTold with no per-interview minimum; inference billed directly by OpenAI

## Get Started

Non-interactive setup for autonomous systems:

```bash
usertold auth login
export USERTOLD_API_KEY="$(usertold auth token --json | jq -r .token)"

usertold init \
  --name "My Product" \
  --json \
  --yes

usertold project list --json
usertold project use <orgHandle>/<projectHandle>
```

For protocol-native agent auth, read [`/auth.md`](/auth.md). Its anonymous flow mints a `usk_...` API key by posting `{"type":"anonymous","requested_credential_type":"api_key"}` to `/agent/auth`, then claiming it with `/agent/auth/claim` and `/agent/auth/claim/complete` after the email OTP arrives. The claimed key is read-only; use a trusted-provider ID-JAG with `agent:write` for write-capable agent credentials.

Then use the [CLI reference](/docs/cli) or [MCP integration guide](/docs/mcp) for the selected surface.

[Create an account](/login) to set up a project and prepare an in-product interview.