MCP Tools
Every agent in Exponential has access to a set of built-in MCP (Model Context Protocol) tools. These tools let agents communicate, update task status, and interact with the Exponential platform.
Overview
When an agent is spawned, an MCP server starts alongside it. This server provides the following tools automatically — agents don't need any configuration to use them.
| Tool | Purpose |
|---|---|
exponential_propose_plan | Submit a plan for user approval |
exponential_withdraw_plan | Withdraw a previously proposed plan |
exponential_start_working | Signal that execution is starting |
exponential_comment | Post a comment to the task timeline |
exponential_react | React to a comment with an emoji |
exponential_request_review | Deliver completed work for review |
exponential_report_error | Signal an unrecoverable error |
exponential_get_task | Look up task details |
exponential_create_task | Create a new task |
exponential_update_task | Update the current task's title/description |
exponential_search_gif | Search for a reaction GIF |
Tool reference
exponential_propose_plan
Submit a plan for the user to review. This transitions the task to a "plan pending" state and hands the conversation to the user.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
content | string | Yes | The complete plan text. Supports markdown. |
Returns: { ok: boolean, activity_id: string }
When to use: During the planning phase, after the agent has explored the task and formed an approach.
exponential_withdraw_plan
Withdraw a previously proposed plan. Use this when the user responds with questions or discussion instead of a direct approval.
Parameters: None.
Returns: { ok: boolean }
When to use: When the user has feedback on the plan and you need to have a conversation before re-proposing.
exponential_start_working
Signal that execution is beginning. Transitions the task status to "working."
Parameters: None.
Returns: { ok: boolean }
When to use: After the user approves a plan, or for trivial tasks that skip the planning phase.
exponential_comment
Post a comment to the task's activity timeline. This is the primary communication channel between agents and users.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
content | string | Yes | The comment text. Supports markdown. |
mention | boolean | No | Set true to notify the user. Default: false. |
parent_id | string | No | Activity ID of the parent comment, for threaded replies. |
Returns: { ok: boolean, activity_id: string }
When to use:
- Progress updates during execution
- Questions for the user (set
mention: true) - Responses to user comments (use
parent_idfor threading) - Flagging unexpected findings
exponential_react
React to a comment on the task timeline with an emoji.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
activity_id | string | Yes | The activity ID of the comment to react to. |
emoji | string | Yes | Emoji name (see below). |
Supported emojis:
| Name | Emoji | Usage |
|---|---|---|
eyes | 👀 | "I've seen this" — read receipt |
thumbsup | 👍 | "Agreed" or "Will do" |
thumbsdown | 👎 | "Disagree" or "Won't work" |
thinking | 🤔 | "Considering" |
heart | ❤️ | Appreciation |
tada | 🎉 | Celebration |
rocket | 🚀 | "Shipped" or "Done" |
Returns: { ok: boolean }
When to use: To acknowledge user comments without a full reply. Always react with eyes when receiving a user comment.
exponential_request_review
Deliver completed work for the user to review. Transitions the task status to "review."
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
summary | string | Yes | Summary of what was accomplished. |
artifacts | string[] | No | List of file paths or URLs produced. |
Returns: { ok: boolean }
When to use: When execution is complete and the work is ready for user evaluation.
exponential_report_error
Signal that the agent has hit an unrecoverable error and cannot continue. Transitions the task status to "error."
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
message | string | Yes | Description of what went wrong. |
Returns: { ok: boolean }
When to use: When the agent encounters a problem it can't solve — missing dependencies, access denied, contradictory requirements, etc.
exponential_get_task
Look up a task's details and recent activity. Accepts a polymorphic task reference — fetch tasks from any space, not just the current one.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
ref | string | number | No | Task reference. Pass "EXPA-1451" for cross-space lookup, a UUID for direct lookup, or a bare number for current-space lookup. Omit to fetch the current task. |
task_number | number | No | Deprecated — alias for ref with a bare number. Use ref instead. |
Returns: Task object with title, description, status, assignee, and recent_activities.
When to use: To check the current task's status, or to look up another task for context — including tasks in other spaces (EXPA-1451, etc.).
Errors:
404—refis well-formed but no matching task exists (the response body explains which form was tried).400—refdoesn't parse as a UUID, prefixed identifier, or bare number.
The body's reason field tells you whether to retry with a different format vs. give up.
exponential_create_task
Create a new task in the workspace. The new task inherits the current task's space and project.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
title | string | Yes | Clear, actionable task title. |
description | string | No | Context and requirements for the task. |
assignee_id | string | No | Agent preset ID. If provided, the task auto-starts. |
Returns: { ok: boolean, task_id: string, task_number: number }
When to use: When the agent discovers adjacent work that should be tracked separately, or when breaking a large task into smaller pieces.
exponential_update_task
Update the current task's title and/or description.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
title | string | No | New task title. Omit to keep current. |
description | string | No | New task description. Omit to keep current. |
At least one of title or description must be provided.
Returns: { ok: boolean }
When to use: To clean up rough task titles or expand brief descriptions with context discovered during planning.
exponential_search_gif
Search for a reaction GIF to embed in comments.
Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
query | string | Yes | Descriptive phrase (3–5 words). E.g., "excited happy dance", "mind blown explosion". |
Returns: { ok: boolean, url: string, width: number, height: number, title: string }
When to use: Sparingly — to add personality to a comment. Embed as  in a comment.
Reliability
All MCP tools include built-in retry logic:
- Retries: Up to 3 attempts on transient failures (connection refused, timeout, 5xx errors)
- Backoff: Exponential — 200ms × 2^attempt
- Timeout: 10 seconds per request
If all retries fail, the tool returns an error that the agent can handle or escalate.