# MCP tools

> What an assistant connected to Middleout can query and record, with the parameters of each tool.

Every tool acts **as the person who connected the assistant**: it sees only what that person can see in Middleout. If something does not exist or is not visible to them, the answer is the same: not found.

Memory objects are identified by a **handle**, which the search tools return and the read tools receive.

## Query

| Tool | What it is for | Parameters |
| --- | --- | --- |
| `ask` | Ask Middleout a business question and get its grounded answer, with the sources it cites. | `question`; `investigation_id` (optional) to ask within an investigation. |
| `search_knowledge` | Find what the company knows about something, by meaning or by record number. | `query`; `types` (optional); `limit` (up to 20, 10 by default). |
| `read_object` | Read a whole object: its fields, its sources and, for a mental model, its causes. | `handle`. |
| `get_neighbourhood` | See what surrounds an object in the graph. | `handle`; `depth` (1 or 2). |
| `get_knowledge_map` | See at a glance what the company knows: its areas and the totals by type. | None. |
| `get_instructions` | Read the instructions for working in a connected repository: its `AGENTS.md` and `CLAUDE.md` files. | `repository` (`owner/name`). |
| `list_investigations` | List the investigations you can open, newest first. | `limit` (up to 50, 20 by default). |
| `read_investigation` | Read an investigation: its question, its goal and what people have already concluded. | `investigation_id`. |

The types `search_knowledge` accepts are: `metric`, `decision`, `definition`, `procedure`, `learning`, `mental_model`, `table` and `document`.

`ask` is limited to **30 questions per hour per person** when used over MCP.

## Record

When something the company should know comes up in the conversation, the assistant can record it in Middleout. What is recorded goes into the memory immediately, with its origin: the assistant that recorded it, on behalf of the person.

| Tool | What it records | Main parameters |
| --- | --- | --- |
| `record_decision` | A decision: the question, what was chosen, the alternatives and the assumptions. If another decision on the same question is recorded, it replaces the previous one, which is kept as history. | `question`, `outcome`, `alternatives`, `assumptions`, `rests_on`, `scope`. |
| `record_teaching` | A teaching: a definition, a rule or a formatting preference. | `statement`, `subject`, `confirmed`, `scope`, `kind` (`definition`, `rule` or `formatting`). |
| `record_relation` | A relation between two objects in the memory, with the quote that backs it. | `source`, `target`, `relation`, `quote`, `confirmed`. |
| `record_question` | An open question nobody has answered yet. | `statement`, `scope`. |
| `record_evidence` | Evidence for or against something the memory already contains. | `statement`, `stance` (`supports` or `contradicts`), `bears_on`, `scope`. |

`scope` says who the record is for: `org` (the whole organization), `team` (your team) or `user` (only you).

## Good practices for agents

- Before answering about the business, search with `search_knowledge` or ask with `ask`: the company may have an agreed definition that differs from the usual one.
- Cite the handles you used, so the person can open them in Middleout.
- Record only what the person confirmed or decided in the conversation, and set `confirmed` when they did so explicitly.
- If a tool says something does not exist, the person may not have access to it. Do not assume it does not exist for the whole company.