---
name: botsona
description: Run AI usability tests on a web app or website with Botsona, then read where people got stuck and what to fix first. Use when the user asks to test a flow (sign-up, checkout, onboarding, a new feature) on a live site, to check a deployed change from a user's point of view, to find usability or accessibility problems on a public page, or asks about their Botsona tests, reports or credits.
---

# Botsona: AI usability tests from your agent

Botsona sends AI testers, each acting like a specific kind of person (a first-timer on a slow
phone, a keyboard-only user, someone with low vision, a skeptical buyer and more), through a web
app in a fresh cloud browser. The user can watch live. When the testers finish, Botsona writes a
report grounded in what they actually did: a verdict, what to fix first, findings with severity,
and what worked.

## Setup

These tools come from the Botsona MCP server at `https://app.botsona.io/mcp` (streamable HTTP,
OAuth sign-in with the user's Botsona account). If the tools below are not available, tell the user
to add that server to this agent and sign in when the browser opens:

- Claude Code: `claude mcp add --transport http --scope user botsona https://app.botsona.io/mcp`,
  then run `/mcp` and choose botsona to sign in.
- Codex: `codex mcp add botsona --url https://app.botsona.io/mcp` (it opens a browser to sign in;
  if it does not, run `codex mcp login botsona`).
- Cursor: add `{"mcpServers": {"botsona": {"url": "https://app.botsona.io/mcp"}}}` to
  `~/.cursor/mcp.json`, then sign in from Cursor's MCP settings.

A free account is enough to start: https://app.botsona.io

## Tools

| Tool | Use it to |
|---|---|
| `start_test` | Start a test. `url` (required): a public web address. `task` (optional): what the testers should try, in plain words. Without a task, it scans the whole site page by page. |
| `get_test` | Read one test: status, credits used, and when done the report (headline, summary, fix first, findings) and its link. |
| `list_tests` | The user's recent tests, newest first. |
| `stop_test` | Stop a running test; what the testers found so far is kept. |
| `get_account` | Plan, credits left this week, extra credits, testers per test. |

## How to run a good test

1. **Get a public URL.** Botsona can only open public addresses. A `localhost` or private-network
   address is refused: deploy a preview first (Vercel, Netlify, a staging URL) and test that. Only
   test sites the user owns or may test.
2. **Write the task as a goal, not as steps.** Good: "Sign up for a free account and create your
   first project." Bad: "Click Sign up, type an email, click Next." The testers must find the way
   themselves; that is what reveals the problems. One flow per test.
3. **Say what must not happen** when it matters: "Do not enter card details." Testers already stop
   before anything that cannot be undone (paying with a real card, deleting, sending messages).
4. **Start it and share the link.** `start_test` returns a link: give it to the user so they can
   watch the testers live.
5. **Wait, then read.** A task test takes about 3 to 8 minutes, a whole-site scan up to 30. Call
   `get_test` about once a minute, not more often. While waiting, continue other work if there is
   any.
6. **Report back plainly:** the verdict and headline, the "fix first" item, then the findings in
   order of severity, each with what happened. Quote the report; do not add findings it does not
   contain. End with the report link (recordings and every step are there).
7. **Offer to fix what you can.** If the findings point at code in this project (a missing label,
   an error message that says nothing, a form that loses input), propose the change, then offer to
   run the same test again after it is deployed to confirm the fix.

## Credits

Each test uses credits from the user's plan, counted by what it actually runs (a short task test
uses a few, a whole-site scan more). Starting needs a few credits left. Before a large scan, or
several tests in a row, check `get_account` and tell the user. If credits run out, the user can buy
more or upgrade in the Botsona app; never try to pay from the agent.

## Typical requests

- "I just shipped the new onboarding. Have Botsona check whether a new user can finish it."
- "Test the checkout on https://staging.example.com, but don't enter a card."
- "What did my last Botsona test find? Fix the top issue."
- "Scan our marketing site for accessibility problems."