# Brain tools reference

> Every tool in Obi's brain over MCP and the Brain API, what each one needs, what it returns and who can use it.

These are the tools an assistant gets after it connects (see [Connect over MCP](https://outbind.ai/docs/connect)). The same tools run over the [Brain API](https://outbind.ai/docs/api). The live list for a connection is always what `tools/list` returns: it depends on the access the person allowed and their role.

**Access** below means: **Read** works with Read only; **Edit** needs Can draft and edit; **Admin** also needs the person to be a workspace owner or admin.

## Naming a prospect

Most tools take a `prospect` object. Give at least one of these; an email is best:

```json
{
  "prospect": {
    "email": "jane@acme.com",
    "first_name": "Jane",
    "last_name": "Doe",
    "title": "Head of Sales",
    "company": "Acme",
    "linkedin_url": "https://www.linkedin.com/in/janedoe",
    "location": "Madrid, Spain"
  }
}
```

Or `{ "prospect": { "lead_id": "…" } }` with the `lead_id` from an earlier answer. A prospect named for the first time is added to the workspace's contacts, so what you learn about them stays with them. Answers name the prospect back as `prospect: { lead_id, name, title, company, open_at }`.

## Learn

| Tool | Access | What it does |
| --- | --- | --- |
| `get_brain` | Read | What Obi knows about the seller: company, website, about, products, ideal customer (target market, industries, company sizes, locations, job titles, seniorities, pain points), goal and the team's lessons. Call it first. Takes no input. |
| `create_icp` | Admin | Reads the seller's website and their own words and writes the ideal customer profile, saved to the brain. Input: `website`, `about` (up to 3,000 characters), `countries`. Ask the person a few questions first if the website is thin. |
| `save_lesson` | Edit | Saves one general sales lesson so every later message uses it. Input: `section` (`who_buys`, `what_works`, `objections`, `timing`, `avoid`, `style` or `preferences`), `lesson` (one sentence, under 240 characters, no names, emails or links). Team lessons need an owner or admin; `style` and `preferences` are the person's own. |
| `remember_prospect` | Edit | Saves what the person learned about a prospect (a call, a reply, their situation). Input: `prospect`, `note`. |
| `recall_prospect` | Read | Everything Obi remembers about a prospect: details, stage, fit score, research brief, notes and recent history. Input: `prospect`. |
| `add_document` | Admin | Teaches Obi from a document. Input: `name` (its title or file name) and the document's `text` (up to 100,000 characters). Read the file the person attached and send its words. Learned like an upload in the app: facts are kept only when a quote backs them. |
| `list_documents` | Read | The documents Obi learned from: name, status, summary and facts. Never their text. |
| `remove_document` | Admin | Removes a document and what Obi learned from it. Input: `document_id` from `list_documents`. |

## Write

Every writing tool writes on Outbind's side with the seller's brain, the prospect's memory, Outbind's playbook, examples and lessons, and its pre-send checks. They return text only: **nothing is sent**. Show the result to the person as it is.

| Tool | Access | What it does |
| --- | --- | --- |
| `write_email` | Edit | A cold first email, or a follow-up when `previous` holds what was already sent (oldest first, each `{ subject, body }`). Input: `prospect`, `instructions` (an angle, an event to mention, the ask), `previous`. Returns `subject`, `body` and `issues` (checks it still fails, if any). |
| `answer_reply` | Edit | Sorts a prospect's reply and writes the answer. Input: `prospect`, `their_reply` (as they wrote it), `your_email` (the email they answered), `instructions`. Returns `label`, `meaning`, `confidence`, `summary`, `follow_up_on` and `answer: { subject, body, issues }`. `answer` is empty for someone who asked to stop or is out of office, with a `next_step` instead. |
| `write_dm` | Edit | A short LinkedIn direct message, or a connection note that fits 200 characters. Input: `prospect`, `instructions`, `previous`. Returns `body` and `issues`. |
| `write_call_script` | Edit | A short cold call script: opener, why you're calling, questions, likely objections with answers, the close and a voicemail. Input: `prospect`, `instructions`, `previous`. |
| `fix_draft` | Edit | Rewrites an email the person wrote to Outbind's standard, keeping their point, their ask and their facts. Input: `prospect`, `draft: { subject, body }`, `instructions`. Returns `subject`, `body`, `issues`. |
| `plan_flow` | Edit | A written plan for a multi-step sequence: who it's for, each step's channel, wait and purpose, and a sample first message. Input: `goal` in their words ("book demos with dental clinics in Spain"). Nothing is created or sent. |

## Judge

| Tool | Access | What it does |
| --- | --- | --- |
| `score_fit` | Edit | How well a prospect fits the ideal customer profile: `tier` (Strong, Good or Weak fit), `score`, `fit`, `intent`, `likely_buyer`, `confidence` and `reasons`. Input: `prospect`. |
| `sort_reply` | Read | What a reply means: interested, wants a meeting, question, concern, referral, not now, not interested, asked to stop or out of office, how sure it is, and when to get back to them if they said. Input: `their_reply`, and `prospect` if known. |
| `research_prospect` | Edit | A brief from the company's own pages, the prospect's public posts and recent company news: who they are, why now, the angle and talking points, each with its source. Saved to their memory. Takes up to a minute. Input: `prospect`. |
| `verify_emails` | Edit | Checks up to 25 addresses with Outbind's own checker. Each comes back Valid, Invalid, Risky or Unknown, with the reason, a suggested fix for a typo, and whether it's a role address or disposable. Free, within the plan's daily limit. Input: `emails`. |

## Errors

A tool that fails answers with an error message meant for the person: read it to them. Common ones: the prospect wasn't named, the person's role can't do this, the plan's limit is reached (with what it is), or too many calls in a short time. A tool the connection can't use answers exactly like one that doesn't exist.

## Example session

1. `get_brain` shows the ideal customer is empty.
2. Ask the person what they sell and who buys, then `create_icp` with `website: "acme.com"` and their answer in `about`.
3. `research_prospect` for `jane@acme.com`, then `write_email` for her.
4. The person says Jane prefers short emails: `remember_prospect` with that note.
5. A week later, `write_email` with `previous` holding the first email gives the follow-up.
6. Jane replies: `answer_reply` with her words and the email she answered.