Tools Reference - emma Documentation

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.

Example Request
Example Response

{}

Emma Remote MCP Server: healthy. API key is valid.

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.

string

required

Search keywords, natural language or terms.Examples: "post slack message", "create github issue"

string

Optional service filter, e.g. "slack", "github", "notion", "gmail".

integer

default:"20"

Maximum number of results (max 100).

Example Request
Example Response

{
  "query": "post slack message",
  "service": "slack",
  "limit": 5
}

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

emma_get_tool_schema

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

string

required

The exact tool name (e.g. "slack_post_message", "github_create_issue"). Get this from emma_search_tools.

Example Request
Example Response
Example Response (success)
Example Response (auth required)

{
  "tool_name": "slack_post_message"
}

**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, textNext 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!\"}"
}

Tool: slack_post_message
Duration: 412ms
Session: tool_a1b2c3d4e5f6

Result:
{
  "ok": true,
  "message_ts": "1735282800.000100"
}

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.

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.

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.

string

Optional filter matched against Skill name/summary. Leave empty to return all Skills.

integer

default:"20"

Maximum number of results per page (max 100).

integer

default:"0"

Number of results to skip, for pagination.

Example Request
Example Response

{
  "query": "",
  "limit": 20,
  "offset": 0
}

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.

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.

string

required

The exact Skill ID. Get this from emma_list_skills.

Example Request
Example Response

{
  "skill_id": "3f1a9e2b-1234-4c56-9abc-1234567890ab"
}

**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.

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.

string

required

Short, descriptive Skill name.

string

required

What the Skill does and when to use it (used for discovery via emma_list_skills).

string

required

Step-by-step workflow/instructions to follow. Reference emma tools where relevant.

Example Request
Example Response

{
  "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."
}

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`.

emma_update_skill

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

string

required

The exact Skill ID. Get this from emma_list_skills.

string

New name (leave empty to keep current).

string

New summary/description (leave empty to keep current).

string

New instructions body (leave empty to keep current).

Example Request
Example Response

{
  "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."
}

Skill updated.
skill_id: 3f1a9e2b-1234-4c56-9abc-1234567890ab
name: Weekly Status Report
version: 2

emma_delete_skill

Delete a Skill.

string

required

The exact Skill ID. Get this from emma_list_skills.

Deleting a Skill is permanent and cannot be undone.

Example Request
Example Response

{
  "skill_id": "3f1a9e2b-1234-4c56-9abc-1234567890ab"
}

Skill deleted: 3f1a9e2b-1234-4c56-9abc-1234567890ab

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

​Health Check

​emma_health_check

​Tool Vendor

​emma_search_tools

​emma_get_tool_schema

​Skill Vendor

​emma_list_skills

​emma_get_skill

​emma_create_skill

​emma_update_skill

​emma_delete_skill

​Error Responses

Health Check

emma_health_check

Tool Vendor

emma_search_tools

emma_get_tool_schema

Skill Vendor

emma_list_skills

emma_get_skill

emma_create_skill

emma_update_skill

emma_delete_skill

Error Responses