> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shanone.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Reference

> Complete reference documentation for all emma MCP Server tools with parameters, examples, and return values.

This page provides detailed documentation for all 9 tools available in the emma MCP Server. All tools return plain text (formatted with Markdown), not structured JSON — the example responses below show the shape of that text.

## Health Check

### emma\_health\_check

Check emma MCP server connectivity and authentication status. Use this to verify your API key is valid before running other tools. Takes no parameters.

<Tabs>
  <Tab title="Example Request">
    ```json theme={null}
    {}
    ```
  </Tab>

  <Tab title="Example Response">
    ```
    Emma Remote MCP Server: healthy. API key is valid.
    ```
  </Tab>
</Tabs>

***

## Tool Vendor

The Tool Vendor tools let your agent discover and execute any of emma's integrations (Slack, GitHub, Notion, Gmail, and 100+ others) without needing a dedicated MCP tool per integration action.

**Recommended workflow:** `emma_search_tools` → `emma_get_tool_schema` (if needed) → `emma_execute_tool`.

### emma\_search\_tools

Search for integration tools by keyword. Returns matching tools with name, service, and description.

<ParamField path="query" type="string" required>
  Search keywords, natural language or terms.

  **Examples:** `"post slack message"`, `"create github issue"`
</ParamField>

<ParamField path="service" type="string">
  Optional service filter, e.g. `"slack"`, `"github"`, `"notion"`, `"gmail"`.
</ParamField>

<ParamField path="limit" type="integer" default="20">
  Maximum number of results (max 100).
</ParamField>

<Tabs>
  <Tab title="Example Request">
    ```json theme={null}
    {
      "query": "post slack message",
      "service": "slack",
      "limit": 5
    }
    ```
  </Tab>

  <Tab title="Example Response">
    ```
    Found 1 tool(s) for "post slack message" (service: slack):

    - **slack_post_message** (slack)
      Post a message to a Slack channel or user.

    **Next steps:**
    1. Use `emma_get_tool_schema` to see the input schema for a tool
    2. Use `emma_execute_tool` to execute the tool with arguments
    ```
  </Tab>
</Tabs>

***

### emma\_get\_tool\_schema

Get the JSON Schema for a specific integration tool's input arguments.

<ParamField path="tool_name" type="string" required>
  The exact tool name (e.g. `"slack_post_message"`, `"github_create_issue"`). Get this from `emma_search_tools`.
</ParamField>

<Tabs>
  <Tab title="Example Request">
    ```json theme={null}
    {
      "tool_name": "slack_post_message"
    }
    ```
  </Tab>

  <Tab title="Example Response">
    ````
    **slack_post_message**

    Post a message to a Slack channel or user.

    **Input Schema:**
    ```json
    {
      "type": "object",
      "properties": {
        "channel": { "type": "string", "description": "Channel name or ID, e.g. #general" },
        "text": { "type": "string", "description": "Message text to post" }
      },
      "required": ["channel", "text"]
    }
    ````

    **Required arguments:** channel, text

    **Next step:** Use `emma_execute_tool` with tool\_name="slack\_post\_message" and the required arguments.

    ````
    </Tab>
    </Tabs>

    ---

    ### emma_execute_tool

    Execute a specific integration tool with arguments. OAuth is handled by emma — if the tool requires authentication you haven't set up, you get a connect link back instead of an error.

    <ParamField path="tool_name" type="string" required>
    The exact tool name to execute (e.g. `"slack_post_message"`). Get this from `emma_search_tools`.
    </ParamField>

    <ParamField path="arguments" type="string" required>
    Tool arguments as a **JSON string** (not a JSON object). Example: `'{"channel": "#general", "text": "Hello!"}'`. Pass `'{}'` for tools with no arguments.
    </ParamField>

    <ParamField path="session_id" type="string">
    Optional session ID for stateful/multi-step execution. Omit for a stateless call — a new session ID is generated and returned.
    </ParamField>

    <Tabs>
    <Tab title="Example Request">
    ```json
    {
      "tool_name": "slack_post_message",
      "arguments": "{\"channel\": \"#general\", \"text\": \"Hello from Cursor!\"}"
    }
    ````
  </Tab>

  <Tab title="Example Response (success)">
    ```
    Tool: slack_post_message
    Duration: 412ms
    Session: tool_a1b2c3d4e5f6

    Result:
    {
      "ok": true,
      "message_ts": "1735282800.000100"
    }
    ```
  </Tab>

  <Tab title="Example Response (auth required)">
    ```
    Authentication Required

    Tool: slack_post_message
    Service: slack
    Reason: auth_required
    Auth Type: oauth2

    Slack への接続が必要です。

    Connect Link: https://app.emma.ai/connect/slack?request=req_abc123

    Please ask the user to visit the connect link to authenticate, then retry the request.
    ```
  </Tab>
</Tabs>

<Note>
  When `reason` is `auth_required` or `auth_expired`, surface the `Connect Link` to the user. Once they authenticate, retry the same `emma_execute_tool` call.
</Note>

***

## Skill Vendor

A **Skill** is a named, reusable prompt describing how to accomplish a task — essentially an Agent Skill (`name` + `summary`/description + `instructions`/body). Skills are stored in emma's cloud, so they're reproducible across machines, IDEs, and agents, and they also appear in emma's Web UI under the **Skills** tab.

**Recommended workflow:** call `emma_list_skills` before starting a task to check whether a relevant Skill already exists, then `emma_get_skill` to read it and follow its instructions yourself.

### emma\_list\_skills

List saved Skills, newest first. By default returns **all** Skills (paginated) — `query` is an optional filter, not a required keyword search.

<ParamField path="query" type="string">
  Optional filter matched against Skill name/summary. Leave empty to return all Skills.
</ParamField>

<ParamField path="limit" type="integer" default="20">
  Maximum number of results per page (max 100).
</ParamField>

<ParamField path="offset" type="integer" default="0">
  Number of results to skip, for pagination.
</ParamField>

<Tabs>
  <Tab title="Example Request">
    ```json theme={null}
    {
      "query": "",
      "limit": 20,
      "offset": 0
    }
    ```
  </Tab>

  <Tab title="Example Response">
    ```
    Showing 2 of 2 skill(s) (offset=0):

    - **Weekly Status Report** (skill_id: 3f1a9e2b-1234-4c56-9abc-1234567890ab)
      Gathers last week's closed issues and posts a summary to Slack #team.
    - **Daily Standup Reminder** (skill_id: 7c2b5f8d-5678-4d9e-bcde-234567890abc)
      Posts a standup reminder to Slack #general every weekday morning.

    **Next step:** Use `emma_get_skill` with a skill_id to read the full instructions, then follow them.
    ```
  </Tab>
</Tabs>

***

### emma\_get\_skill

Get a Skill's full instructions (body). The returned text is a prompt/workflow — after reading it, your agent should follow the steps itself, using `emma_search_tools` / `emma_get_tool_schema` / `emma_execute_tool` for any integration actions required.

<ParamField path="skill_id" type="string" required>
  The exact Skill ID. Get this from `emma_list_skills`.
</ParamField>

<Tabs>
  <Tab title="Example Request">
    ```json theme={null}
    {
      "skill_id": "3f1a9e2b-1234-4c56-9abc-1234567890ab"
    }
    ```
  </Tab>

  <Tab title="Example Response">
    ```
    **Weekly Status Report**

    Gathers last week's closed issues and posts a summary to Slack #team.

    **Instructions:**
    1. Use emma_execute_tool with github_list_issues to fetch issues closed in the last 7 days.
    2. Summarize them into 3-5 bullet points.
    3. Use emma_execute_tool with slack_post_message to post the summary to #team.

    **Next step:** Follow these instructions. Use `emma_execute_tool` for any integration actions required.
    ```
  </Tab>
</Tabs>

***

### emma\_create\_skill

Save a reusable workflow as a new Skill. Use this after completing a task worth reusing later from a different machine, IDE, or agent. All three arguments are required.

<ParamField path="name" type="string" required>
  Short, descriptive Skill name.
</ParamField>

<ParamField path="description" type="string" required>
  What the Skill does and when to use it (used for discovery via `emma_list_skills`).
</ParamField>

<ParamField path="body" type="string" required>
  Step-by-step workflow/instructions to follow. Reference emma tools where relevant.
</ParamField>

<Tabs>
  <Tab title="Example Request">
    ```json theme={null}
    {
      "name": "Weekly Status Report",
      "description": "Gathers last week's closed issues and posts a summary to Slack #team.",
      "body": "1. Use emma_execute_tool with github_list_issues to fetch issues closed in the last 7 days.\n2. Summarize them into 3-5 bullet points.\n3. Use emma_execute_tool with slack_post_message to post the summary to #team."
    }
    ```
  </Tab>

  <Tab title="Example Response">
    ```
    Skill created.
    skill_id: 3f1a9e2b-1234-4c56-9abc-1234567890ab
    name: Weekly Status Report

    Retrieve it later with `emma_get_skill` or find it with `emma_list_skills`.
    ```
  </Tab>
</Tabs>

***

### emma\_update\_skill

Update an existing Skill. Only non-empty fields are changed.

<ParamField path="skill_id" type="string" required>
  The exact Skill ID. Get this from `emma_list_skills`.
</ParamField>

<ParamField path="name" type="string">
  New name (leave empty to keep current).
</ParamField>

<ParamField path="summary" type="string">
  New summary/description (leave empty to keep current).
</ParamField>

<ParamField path="instructions" type="string">
  New instructions body (leave empty to keep current).
</ParamField>

<Tabs>
  <Tab title="Example Request">
    ```json theme={null}
    {
      "skill_id": "3f1a9e2b-1234-4c56-9abc-1234567890ab",
      "instructions": "1. Use emma_execute_tool with github_list_issues (last 7 days).\n2. Summarize into bullet points.\n3. Post to Slack #team AND #eng-leads."
    }
    ```
  </Tab>

  <Tab title="Example Response">
    ```
    Skill updated.
    skill_id: 3f1a9e2b-1234-4c56-9abc-1234567890ab
    name: Weekly Status Report
    version: 2
    ```
  </Tab>
</Tabs>

***

### emma\_delete\_skill

Delete a Skill.

<ParamField path="skill_id" type="string" required>
  The exact Skill ID. Get this from `emma_list_skills`.
</ParamField>

<Warning>
  Deleting a Skill is permanent and cannot be undone.
</Warning>

<Tabs>
  <Tab title="Example Request">
    ```json theme={null}
    {
      "skill_id": "3f1a9e2b-1234-4c56-9abc-1234567890ab"
    }
    ```
  </Tab>

  <Tab title="Example Response">
    ```
    Skill deleted: 3f1a9e2b-1234-4c56-9abc-1234567890ab
    ```
  </Tab>
</Tabs>

***

## Error Responses

| Situation                                                                | Response                                                              |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| Unknown tool name passed to `emma_execute_tool` / `emma_get_tool_schema` | `Tool not found: <tool_name>` with a hint to use `emma_search_tools`  |
| Unknown `skill_id` passed to any Skill Vendor tool                       | `Skill not found: <skill_id>` with a hint to use `emma_list_skills`   |
| Invalid JSON passed to `emma_execute_tool`'s `arguments`                 | `Invalid JSON in arguments: ...` with the expected format             |
| Integration requires OAuth and isn't connected yet                       | `reason: "auth_required"` (or `"auth_expired"`) plus a `connect_link` |
| HTTP-level authentication failure (bad/missing API key)                  | `401` with `error: "api_key_required"` or `"invalid_api_key"`         |
| Too many requests                                                        | `429` with `error: "rate_limit_exceeded"` and a `Retry-After` header  |