Sasha MCP reference

Research run tools (surveyPublicContext, checkSurvey)

Tool names: surveyPublicContext, checkSurvey

Scopes: knowledge:read, knowledge:write, skills:run-contained

When to use

Use these two tools to draft the Public Context documents of a business brain from public sources: the legal entity, the offer, the market position and the public footprint. surveyPublicContext starts the run. checkSurvey reports it.

The tools are in the tool list only when all of these are true:

  • The instance has research runs turned on. They are off by default, and the instance's operator turns them on.
  • The instance has document writing turned on, because the run saves its documents through the same path as writeDoc.
  • The person who connected is a member. An admin or staff connection never gets these tools. The tools are absent, not refused.
  • The connection holds knowledge:read, knowledge:write and skills:run-contained. The last scope is never in a default grant: it must be asked for by name when the token is made, and an administrator must allow it for the person. A connection made without it does not gain it: the person must reconnect, or mint a new token.

What a run does:

  • It works in a closed folder of its own, with read-only copies of the brain's documents, the web, and no other tool. It cannot read another person's documents.
  • It writes only documents that do not exist yet. It never replaces a document. For a document that already exists, it writes a suggestion into _public-context-suggestions.md in the brain folder, and leaves the document unchanged.
  • It writes a receipt, _setup-public-context-run.md, in the brain folder.
  • It takes 5 to 25 minutes.

The owner must confirm who the business is before you start a run: identity is used as given.

surveyPublicContext takes:

  • brain: a brain id from listBrains, <project>/<folder>. The folder can be new, with no brain.md yet: the run then creates brain.md.
  • runId: your own id for this run, 8 to 64 characters of letters, digits, ., _ or -. A UUID is good. A second call with the same runId returns that run while it runs or after it succeeded. After a run that failed, timed out or ended partial, the same runId starts the next attempt, which skips the documents the earlier attempt created.
  • identity: legalName and website are required; tradingName, companyNumber, registry, country, leaders (a list of { "name", "role" }) and ownerNotes (up to 1,000 characters) are optional. An unknown field is refused.

It returns runId, executionId, attempt, status (running for a new run), target, and two lists of document ids: willCreate (documents that do not exist yet) and willSuggest (documents that exist, so the run can only suggest). A repeated call also returns reused: true.

checkSurvey takes runId. It returns status (running, completed, partial, failed or timeout), attempt, summary, error, the times, and, when the run has finished, receipt with created, suggested, refused (each with a path and a reason), warnings and token usage. Wait two minutes between polls.

Example

A member starts a run on their business brain:

{
  "brain": "member-14/brains/business",
  "runId": "9b2f4c1e-7d3a-4e8b-a0c5-3f6e1d2b4a87",
  "identity": {
    "legalName": "Northwind Advisory Ltd",
    "website": "https://example.com",
    "companyNumber": "01234567",
    "registry": "Companies House",
    "country": "United Kingdom"
  }
}

{
  "runId": "9b2f4c1e-7d3a-4e8b-a0c5-3f6e1d2b4a87",
  "executionId": "3f2b9c1e-7a4d-4c3b-9a1e-0123456789ab",
  "attempt": 1,
  "status": "running",
  "target": { "brain": "member-14/brains/business" },
  "willCreate": ["brain", "legal-entity-and-ownership", "market-position-and-competitors", "public-footprint", "knowledge-synthesis", "citations"],
  "willSuggest": ["offer-surface"]
}

Later, checkSurvey with the same runId (shortened):

{
  "runId": "9b2f4c1e-7d3a-4e8b-a0c5-3f6e1d2b4a87",
  "attempt": 1,
  "status": "completed",
  "summary": "setup-public-context v1: drafted 6 documents, suggested changes to 1, 2 inconsistencies",
  "error": null,
  "receipt": {
    "created": ["brain", "legal-entity-and-ownership", "market-position-and-competitors", "public-footprint", "knowledge-synthesis", "citations"],
    "suggested": ["offer-surface"],
    "refused": [],
    "warnings": []
  }
}

Refusals and what to do

A refusal is an error result with the text Error in <tool>: <reason>.

  • Not found: the brain is not one this person can write, or it does not exist, or (for checkSurvey) the run is not one of this person's runs. All of these give the same answer. Use a brain from listBrains in the person's own home.
  • rate_limited:member_run_in_progress (recoverable: …) {"retryAfterSeconds":120,"runId":"…"}: another run of this person is still running. Poll checkSurvey with the runId named, and start the next run when it has finished.
  • rate_limited:member_daily_cap, rate_limited:member_token_budget, rate_limited:instance_busy or rate_limited:instance_daily_cap, each followed by (recoverable: …) and {"retryAfterSeconds":N}: a limit is reached. Start the run again after that many seconds, with the same runId and the same identity.
  • invalid_input:arguments_invalid (<fields>): the arguments do not match the schema, for example a runId with a : or an unknown field in identity.
  • A finished run whose receipt.refused lists target_exists is not a fault: that document already existed, so its text is in _public-context-suggestions.md. Read it with readDoc, and change the document only when the person agrees.
  • status failed with error interrupted means the server restarted during the run; authority_lost means the person's access changed during the run, so nothing was written. Start again with the same runId when that is right.
  • If these tools are not in your tool list, a call returns MCP error -32602: Tool surveyPublicContext not found. One of the conditions above is not true. Read the surveys and permissions sections of getDocs. Do not tell the person that Sasha cannot do research.

Related

  • listBrains and getBrain give the brain id and the state of each document.
  • readDoc reads the documents, the suggestions file and the receipt.
  • writeDoc is the path the run saves through, under the same permissions.
  • getDocs has the surveys and permissions sections.
made with bernard

Cookie settings