Sasha MCP reference

Skill tools (skill_<name>)

Tool names: skill_<name>

Scopes: skills:run

When to use

A skill is a packaged way of doing a task that Sasha can run, for example a report, a research run or a data job. Each skill that the organisation enables for external use is a tool named skill_<name>, where <name> is the skill's folder name. For example, the skill weekly-digest is the tool skill_weekly-digest. Read the tool's description: it says what the skill does and which arguments it takes.

A skill tool is in the tool list only when all of these are true:

  • The connection holds skills:run. Only admin and staff can hold it, so a member's connection has no skill tools.
  • The skill is enabled for external use. It has triggers.api: true, or its category is one that the instance exposes automatically (by default, showcase).
  • The skill is not turned off with enabled: false.
  • The folder name has 1 to 50 letters, digits, _ or -.

The tool list is built again for each request, so a new skill appears without a restart. Some clients keep an old tool list. If a skill you expect is missing, the person can reconnect the connector.

Arguments:

  • When the skill declares parameters (api_params), the tool takes them as named arguments. A parameter declared as string, number or boolean must have that type. A parameter with no type, or another type, takes any value.
  • When the skill declares no parameters, the tool takes one optional argument, params, an object of free-form values that the description explains.

A call returns at once with an executionId and status running. The skill runs in the background, usually for 1 to 10 minutes. Poll checkExecution with the executionId, and wait a minute or two between polls. Many skills save their output as a document. checkExecution gives its path as outputPath; read it with readDoc.

There is no confirmation step. A call starts a run each time it is made, so do not repeat a call to check on a run. Use checkExecution.

Example

The skill weekly-digest declares one parameter, weekStart. Call skill_weekly-digest:

{ "weekStart": "2026-09-28" }

The result is JSON text:

{
  "executionId": "3f2b9c1e-7a4d-4e8b-9c61-2d5f0a8b7e14",
  "status": "running",
  "note": "The skill is running in the background. Call checkExecution with this executionId (wait a minute or two between polls); results may also be written into the knowledge base."
}

A skill with no declared parameters takes params:

{ "params": { "audience": "partners" } }

Refusals and what to do

  • If the connection does not hold skills:run, no skill tool is in your tool list, and a call to one returns MCP error -32602: Tool skill_weekly-digest not found (with the name you called). The same answer comes for a skill that is not enabled for external use, or that does not exist. Read the permissions section of getDocs. A scope is never added to an existing connection: the person must reconnect, or mint a new token, with skills:run. Only admin and staff can hold it.
  • When an argument has the wrong type, or a required parameter is missing, the call is refused with MCP error -32602: Input validation error: Invalid arguments for tool skill_<name>: … and no run starts. Read the tool's input schema and call again. An argument that the schema does not name is removed without an error, so check the spelling of each argument.
  • A run that fails is not a refusal of the call. checkExecution reports status failed or timeout and the error.

Related

  • checkExecution polls the run and gives outputPath.
  • readDoc reads the document at outputPath.
  • searchKnowledge finds output that a skill saved somewhere else.
  • getDocs has a skills section.
made with bernard

Cookie settings