Allows AI agents to manage stories, epics, objectives, and teams in Shortcut (formerly Clubhouse) with advanced search, creation, and listing capabilities.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@shortcut-mcp show my open stories"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for interacting with Shortcut (formerly Clubhouse) directly from Claude.
This project is based on the original work by Antonio Lorusso. Mark Madsen's fork extends the original implementation with additional features including advanced search capabilities, improved CLI tools, and enhanced user experience.
Related MCP server: JIRA MCP Tools
View stories, epics, objectives, and teams
Search through stories with advanced filtering options
Create new stories, epics, and objectives
Safe operations only (no updates or deletions)
Archived stories management (excluded by default, with option to include)
Project Deprecation: Updated to use teams instead of projects, as projects have been deprecated by Shortcut
Improved ID Handling: Better support for both numeric IDs and UUID strings for teams and epics
Enhanced Team Support: Improved team assignment when creating and updating stories
Enhanced Search Functionality: Improved search capabilities with support for Shortcut's native query syntax
Advanced Query Operators: Support for operators like type:, state:, owner:, label:, and more
Better Error Handling: More detailed error messages and improved fallback mechanisms
Robust Story ID Handling: Better handling of non-numeric characters in story IDs
Team Management: Added support for assigning teams to stories using team_id and team_name parameters
New Tool: Use the list-teams tool to see all available teams in your Shortcut workspace
Improved Reliability: Better handling of parameters and error conditions
Enhanced Epic Support: Improved support for linking stories to epics
pip install shortcut-mcpFor MacOS users, we recommend using Homebrew and pipx for a cleaner installation:
# Install pipx if you don't have it already
brew install pipx
pipx ensurepath
# Install shortcut-mcp
pipx install shortcut-mcpThis method installs shortcut-mcp in an isolated environment, preventing dependency conflicts with other Python packages.
To upgrade to the latest version:
# Standard upgrade
pip install --upgrade shortcut-mcp
# If installed with pipx
pipx upgrade shortcut-mcp# Install and set up in one step
shortcut-mcp setupYou'll be prompted for your Shortcut API token, which you can find in your Shortcut settings.
Security Note: Your API token grants access to your Shortcut account. Never share it publicly or commit it to version control. The
.envfile is included in.gitignoreto help prevent accidental exposure.
After setup, you can now use the Shortcut tools directly in Claude Desktop. Try these commands:
list-workflows - See all workflow states
list-my-stories - View stories assigned to you
list-stories-by-state-name - View stories in a specific state
advanced-search-stories - Find stories with multiple filters
list-teams - View all teams in your Shortcut workspace
search-stories - Find stories by keywords
list-archived-stories - View archived stories
list-my-archived-stories - View your archived stories
Note: Projects have been deprecated by Shortcut. The
list-projectstool will now inform you to use teams instead. When creating or updating stories, please useteam_idorteam_nameparameters instead of project-related parameters.
If you want to run the server manually:
# Set your API token
export SHORTCUT_API_TOKEN=your_token_here
# Start the server
shortcut-mcp startClone the repository:
git clone https://github.com/idyll/shortcut-mcp.git
cd shortcut-mcpInstall Python with asdf:
asdf installCreate virtual environment and install dependencies:
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e . # Install package in editable modeSet up your environment:
cp .env.example .env
# Edit .env and add your Shortcut API tokenRun the server:
python -m shortcut_mcpshortcut-mcp/
├── src/
│ └── shortcut_mcp/ # Main package directory
│ ├── __init__.py # Package initialization
│ ├── __main__.py # Entry point
│ ├── cli.py # CLI implementation
│ └── server.py # Server implementation
├── pyproject.toml # Project configuration
├── .tool-versions # ASDF version configuration
└── README.mdThe shortcut-mcp setup command will automatically configure Claude Desktop for you. If you want to do it manually, add this to your Claude Desktop config:
On MacOS (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"shortcut": {
"command": "shortcut-mcp",
"args": ["start"],
"env": {
"SHORTCUT_API_TOKEN": "your_token_here"
}
}
}
}On Windows (%AppData%\Claude\claude_desktop_config.json):
{
"mcpServers": {
"shortcut": {
"command": "shortcut-mcp",
"args": ["start"],
"env": {
"SHORTCUT_API_TOKEN": "your_token_here"
}
}
}
}You can test the server using the MCP Inspector:
npx @modelcontextprotocol/inspector shortcut-mcp startThis server implements read-only operations with safe creation capabilities:
Only allows GET (read) and POST (create) operations
No modification or deletion of existing data
All operations are attributed to the API token owner
This project uses asdf for Python version management. The required Python version is specified in .tool-versions.
# Install Python with asdf
asdf install python
# The correct version will be automatically selected based on .tool-versionsWe use pylint for code quality checks. Run it with:
pylint src/shortcut_mcpOnce your code is ready:
# Install build tools
pip install build twine
# Build the package
python -m build
# Upload to PyPI
python -m twine upload dist/*The Shortcut MCP server provides powerful search capabilities through the advanced-search-stories tool:
Owner vs. Requestor: Distinguish between the person assigned to a story (owner) and the person who requested it
Workflow State: Filter by specific workflow states like "In Development" or "Ready for Review"
Time-based Filtering: Find stories based on when they were created or updated
created_after / created_before: Filter by creation date
updated_after / updated_before: Filter by last update date
Archived Stories: All search tools exclude archived stories by default
Use include_archived: true parameter to include archived stories
Dedicated tools for working with archived stories: list-archived-stories and list-my-archived-stories
In Claude, you can use commands like:
"Find stories requested by John but owned by Sarah"
"Show me stories in the Ready for Review state created in the last month"
"Search for stories updated after 2023-01-01 in the In Development state"
"List archived stories in the Done state"
"Show my archived stories from the last quarter"
This makes it easy to find exactly the stories you're looking for, even in large projects with many tickets.
Create a new epic in Shortcut
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Epic name | |
| description | Yes | Epic description | |
| milestone_id | No | Optional milestone ID to associate with the epic |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description fails to disclose behavioral traits such as idempotency, side effects, authentication requirements, rate limits, or what happens upon creation. The bare statement 'Create a new epic' is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and front-loaded, with no wasted words. While it could benefit from slight expansion, it is not overly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite 100% schema coverage, the description lacks critical context: no output format, no success/failure hints, no mention of required permissions, and no explanation of the milestone_id parameter's significance. The tool has 3 parameters and no output schema, so more detail is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add any meaning beyond the schema's parameter descriptions; it repeats no new information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new epic in Shortcut, specifying the resource and action. It is distinct from siblings like create-objective or create-story, though it lacks additional context about what an epic is.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, typical use cases, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new objective in Shortcut
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Objective name | |
| description | Yes | Objective description | |
| status | Yes | Objective status |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It indicates a write operation ('Create') but omits side effects, permissions, or return values, leaving behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence of five words with no unnecessary information, exemplary for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple creation tool with three required parameters and no output schema, the description covers basic purpose but lacks details on return or post-creation behavior, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so parameters are already documented. The description adds no extra meaning beyond the schema, achieving baseline adequacy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new objective in Shortcut' clearly specifies the action (create) and the resource (objective), distinguishing it from sibling creation tools like create-epic and create-story.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives. The description lacks context like 'Use this for objectives, not epics or stories' or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new story in Shortcut
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Story title | |
| description | Yes | Story description | |
| story_type | Yes | Story type (feature, bug, chore) | |
| team_id | No | Team ID to create the story in (group_id in Shortcut API) | |
| team_name | No | Team name to create the story in (alternative to team_id) | |
| epic_id | No | Epic ID to associate with the story | |
| epic_name | No | Epic name to associate with the story (alternative to epic_id) | |
| workflow_state_name | No | Workflow state name (e.g., 'Backlog', 'In Development'). Defaults to 'Backlog' if not specified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as side effects, permissions, rate limits, or outcome. The minimal description fails to add transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters and no output schema, the description is too incomplete. It does not explain what the tool returns or how it behaves with multiple optional parameters like team_id vs team_name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description 'Create a new story in Shortcut' adds no extra parameter meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('create') and resource ('story') in a specific system ('Shortcut'). It differentiates well from sibling tools like 'create-epic' and 'create-objective'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., 'update-story', 'search-stories'). No prerequisites or context for when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific story by ID (fastest way to look up a story)
| Name | Required | Description | Default |
|---|---|---|---|
| story_id | Yes | The ID of the story to retrieve (numeric ID only) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral disclosure. It indicates the tool is a fast lookup for detailed info, but lacks specifics about return format, authentication needs, or rate limits. Adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, focused sentence with no redundancy. Every word serves a purpose: verb, resource, identifier, and performance claim.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one well-documented parameter and no output schema, the description is mostly complete. It could mention what 'detailed information' includes, but the sibling tools context fills gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema description already explains the parameter. The description adds no extra semantics beyond noting 'fastest' and 'detailed', but these do not clarify parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves detailed information for a specific story by ID, using a specific verb and resource. It also adds 'fastest way to look up a story', distinguishing it from sibling tools like search-stories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'fastest way to look up a story' implies this tool is optimal when the story ID is known, contrasting with search methods. However, it does not explicitly exclude alternative scenarios or state prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check the health and connectivity of the Shortcut MCP server
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden of behavioral disclosure. It states 'check health and connectivity' but does not specify what the tool does beyond that—e.g., what specific checks are performed, what the response looks like, or whether it is safe/read-only. This leaves ambiguity for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words. Every part is informative. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description is adequate but incomplete. It fails to explain what the health check returns (e.g., a status object, error messages) or any side effects (none expected). A more complete description would include this information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters with 100% coverage (empty). The description adds meaning beyond the schema by explaining the tool's purpose. For a parameterless tool, a baseline of 4 is appropriate; the description is sufficient though minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description is clear and specific: 'Check the health and connectivity of the Shortcut MCP server'. It uses a distinct verb ('check') and resource ('health and connectivity'), making it easily distinguishable from sibling tools which all deal with specific data entities like stories, epics, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for verifying server status, but provides no explicit guidance on when to use this tool vs alternatives. There is no mention of prerequisites, timing, or distinction from other tools beyond the obvious functional difference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List only archived stories
| Name | Required | Description | Default |
|---|---|---|---|
| owner_name | No | Filter by owner name. Leave empty to see all archived stories. | |
| state_name | No | Filter by workflow state name. Leave empty to see all states. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears the full burden of behavioral disclosure. It only states the basic action with no information about side effects, ordering, pagination, or permission requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is efficient for a simple tool. However, it could be improved by front-loading key constraints.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is too short to be complete. It does not explain that it lists all archived stories by default, nor does it clarify the scope (e.g., personal vs. team-wide) compared to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for both parameters. The description adds no additional meaning beyond the schema, placing it at the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List only archived stories' clearly states the verb and resource. However, it does not distinguish from sibling tools like 'list-my-archived-stories' or 'list-stories-by-state-name', which could also list archived stories under certain conditions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not mention when to use this tool versus alternatives, nor does it specify any prerequisites or constraints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List epics in Shortcut
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by status (to do, in progress, done) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure, but it only says 'List epics'. No mention of read-only nature, return format, or pagination. Insufficient for an agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three words is too concise; it sacrifices completeness. The description adds no value over the tool name and does not earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (one optional param, no output schema), the description is incomplete. It fails to specify that results can be filtered or what the response contains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the only parameter (status), and the description adds no extra meaning beyond the schema. Baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List epics in Shortcut' clearly states the verb and resource, but it does not differentiate from sibling tools like list-objectives or provide any scope details (e.g., 'all epics'). It is barely adequate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives such as list-objectives or list-stories. The description lacks any context about filtering or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List only archived stories assigned to you
| Name | Required | Description | Default |
|---|---|---|---|
| state_name | No | Filter by workflow state name. Leave empty to see all states. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only states what is listed, but does not disclose behavioral aspects such as read-only nature, pagination, sorting, or what fields are returned. For a list operation, this is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately states the tool's purpose. It is front-loaded with the key information, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 optional parameter, no output schema, no annotations), the description is fairly complete in stating what the tool does. However, it lacks details on output format, pagination, or ordering, which could be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional parameter 'state_name', with a clear description in the schema. The tool description does not add additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List only archived stories assigned to you' uses specific verb 'list', specific resource 'archived stories', and adds scope 'assigned to you', clearly distinguishing it from siblings like 'list-archived-stories' (all archived) and 'list-my-stories' (likely non-archived).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the user wants to see their own archived stories, but there is no explicit guidance on when to use this tool versus alternatives like 'list-archived-stories' or 'list-my-stories'. No exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stories assigned to you
| Name | Required | Description | Default |
|---|---|---|---|
| state | No | Filter by workflow state (e.g., 'In Development', 'Ready for Review'). Leave empty for all states. | |
| include_archived | No | Include archived stories (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral traits. It only states the action, omitting side effects, authorization needs, or default behavior (e.g., whether archived are included by default). The agent cannot infer safety or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words. It is front-loaded with the verb and resource, making it easy to quickly understand the tool's core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite low complexity, the description lacks context on when to choose this tool over siblings, what 'assigned to you' entails, and any return value details. With no output schema and no annotations, the agent needs more completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no additional meaning to the parameters. Baseline 3 is appropriate because the schema fully documents both parameters, and the description does not need to repeat them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (list) and the resource (stories assigned to you), distinguishing it from generic list tools. It is specific about the assignment scope, though could be more explicit about 'you' referring to the current user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like list-archived-stories or list-stories-by-state-name. The description does not mention prerequisites or exclusions, leaving the agent without decision context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List objectives in Shortcut
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Filter by status (active, draft, closed) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry behavioral disclosure. It only states the basic action, omitting traits like read-only nature, pagination, ordering, or response structure. This is inadequate for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (5 words), front-loading the action. It avoids unnecessary detail, but could benefit from slightly expanding on scope or optional filtering without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter, but lacks an output schema and does not describe return values. For a list tool, the description is minimally adequate but fails to provide context about objectives or result format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the one parameter 'status' has a clear description and enum values). The tool description adds no additional meaning beyond the schema, meeting baseline expectations but not exceeding them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the verb 'List' and resource 'objectives in Shortcut', clearly indicating the action and scope. However, it does not differentiate from sibling list tools like 'list-epics' or 'list-projects', missing an opportunity to specify unique aspects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With 18 sibling tools including many list operations, the agent has no context for selection, such as whether this lists all objectives or only unfiltered ones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
[DEPRECATED] List all projects in Shortcut. Projects have been deprecated by Shortcut, please use teams instead.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the deprecation status, which is the key behavioral trait. Since there are no annotations, this covers the necessary transparency for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that includes deprecation, functionality, and alternative. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Completely adequate for a deprecated tool: states what it does, that it's deprecated, and what to use instead. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so no additional parameter info is needed. The description adds no param details, but schema coverage is 100% and the tool is trivial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all projects in Shortcut, with a deprecation warning. It effectively communicates the purpose, though the deprecation might cause slight uncertainty about functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use teams instead of this deprecated tool, providing clear when-not-to-use and a direct alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stories by workflow state name
| Name | Required | Description | Default |
|---|---|---|---|
| state_name | Yes | Workflow state name (e.g., 'In Development', 'Ready for Review') | |
| owner_name | No | Filter by owner name. Leave empty for all owners. | |
| include_archived | No | Include archived stories (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral context. It does not mention read-only nature, pagination, sorting, or limits, leaving important traits unspecified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is front-loaded with the key purpose. No unnecessary words, but it may be too brief to be fully informative.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With multiple sibling tools, no output schema, and no annotations, the description should provide more context about output format, ordering, or differentiation from similar tools. It currently lacks this completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for all three parameters (100% coverage). The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists stories based on a workflow state name, which is a specific verb-resource combination. However, it does not differentiate from the sibling tool 'list-stories-by-status', which could cause confusion as both filter on workflow-related criteria.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool over alternatives like 'list-stories-by-status' or 'search-stories'. The context signals show several sibling tools with overlapping functionality, making usage scenarios unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List stories by workflow state ID
| Name | Required | Description | Default |
|---|---|---|---|
| workflow_state_id | Yes | Workflow state ID | |
| owner_name | No | Filter by owner name | |
| include_archived | No | Include archived stories (default: false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond filtering by workflow state ID. Missing details on return format, pagination, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, but it merely restates the name. While concise, it does not provide additional useful information beyond the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters and no output schema, the description is too minimal. It lacks context on how the result is returned, and the many sibling tools suggest a need for better differentiation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the parameters. The description adds no extra meaning beyond what is in the schema, resulting in baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List stories by workflow state ID', specifying the verb and resource. However, it does not differentiate from the sibling tool 'list-stories-by-state-name', which suggests a similar purpose but with a different identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'list-stories-by-state-name'. The description only states the basic function, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all teams in Shortcut
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only says 'List all teams' without disclosing behavioral aspects like return format or pagination. Minimal but adequate for a no-parameter retrieval.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words. Perfectly concise for the simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks details about the output format or that it returns full team objects, but for a no-parameter list, it is nearly complete. Could be slightly improved.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters, so description does not need to add meaning beyond schema. Baseline 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists all teams in Shortcut, with a specific verb and resource. It distinguishes from sibling list tools like list-epics or list-projects by mentioning 'teams'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives. Usage is implied as a simple list operation, but no when-not or alternative scenarios are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all workflows and their states
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, data freshness, or side effects. The description carries the full burden but fails to mention that listing is safe and has no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. It front-loads the verb and resource effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description does not explain the return format (e.g., what fields represent state). For a trivial tool with no parameters, it is minimally adequate, but lacks completeness in explaining the meaning of 'states' or expected output structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the baseline is 4. The description adds no param-specific meaning, but this is acceptable because the schema coverage is 100% and there is nothing to elaborate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'list' and the resource 'all workflows and their states', which is a specific verb-resource combination. It distinguishes from siblings like list-epics and list-objectives by targeting workflows, but does not explain what a workflow is. Given the simplicity, it is clear but not exceptional.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidelines are provided on when to use this tool versus alternatives. The description does not specify context, exclusions, or prerequisites. An agent receives no help distinguishing when list-workflows is appropriate compared to other list tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for stories in Shortcut using powerful search operators
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query with optional operators (e.g., 'SMS type:feature state:"In Development" owner:john label:urgent'). Supports operators like type:, state:, owner:, label:, has:attachment, is:blocked, etc. | |
| owner_name | No | Filter by owner name (person assigned to the story). Will be converted to owner:mention_name in the query. | |
| requestor_name | No | Filter by requestor name (person who requested the story). Will be converted to requester:mention_name in the query. | |
| state_name | No | Filter by workflow state name (e.g., 'In Development', 'Ready for Review'). Will be converted to state:"name" in the query. | |
| created_after | No | Filter by creation date (YYYY-MM-DD). Can use 'yesterday' or 'today'. Will be converted to created:date..* in the query. | |
| created_before | No | Filter by creation date (YYYY-MM-DD). Can use 'yesterday' or 'today'. Will be converted to created:*..date in the query. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as pagination, result format, rate limits, or auth requirements. The description only says 'Search for stories', leaving agents unaware of important behavioral details beyond the input schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence, which is efficient. It front-loads the key information. However, it could be slightly expanded without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet the description does not explain return values. Given 6 optional parameters and the complexity of a search tool, the description lacks details on pagination, result format, or error handling. The agent is left without critical completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description briefly mentions operators, but the schema already explains them thoroughly. The description adds minimal value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search for stories in Shortcut using powerful search operators', specifying the verb (search), resource (stories), and tool (Shortcut). It differentiates from sibling tools like list-stories-by-state-name or get-story by implying full-text search with operators.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description hints at usage via 'powerful search operators' but does not explicitly state when to use this tool versus alternatives like list-stories-by-state-name or list-stories-by-status. No exclusions or when-not advise provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing story in Shortcut
| Name | Required | Description | Default |
|---|---|---|---|
| story_id | Yes | Story ID to update | |
| name | No | New story title | |
| description | No | New story description | |
| story_type | No | New story type (feature, bug, chore) | |
| workflow_state_name | No | New workflow state name (e.g., 'Backlog', 'In Development') | |
| epic_id | No | New epic ID for the story | |
| epic_name | No | New epic name for the story | |
| team_id | No | New team ID for the story (group_id in Shortcut API) | |
| team_name | No | New team name for the story (alternative to team_id) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states 'update' without indicating idempotency, side effects, authentication needs, or error behavior. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (one sentence) but underspecified. It lacks front-loaded critical information. Conciseness is positive, but here it sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 9 parameters, no output schema, and no annotations, the description does not provide enough context for an agent to confidently invoke the tool. It omits return value, behavior when updating partial fields, and error cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema. It does not clarify relationships like epic_id vs epic_name or constraints on values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing story in Shortcut' clearly indicates the action (update) and resource (story), but does not differentiate from sibling tools like 'update-story-status', which also updates a story. However, it is not a tautology and provides basic purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., update-story-status) or any context like prerequisites or limitations. The description is silent on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a story's status in Shortcut
| Name | Required | Description | Default |
|---|---|---|---|
| story_id | Yes | Story ID to update | |
| status | Yes | New status for the story (e.g., 'Backlog', 'In Development') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits such as permissions required, validation of status values, side effects, or return information. The agent is in the dark about what happens when the tool is invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the purpose. It is concise, but lacks additional context that could be included without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema and no behavioral details, the description is incomplete. It does not explain the expected outcome, error conditions, or dependencies on workflow state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what is already in the schema for 'story_id' and 'status'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'story's status', which matches the tool name. It is specific enough to distinguish from the sibling 'update-story' tool, but could explicitly mention that it only updates the status field.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling 'update-story' tool. Agents are left to infer the specialization from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.2.3create-epiccreate-objectivecreate-storyget-storyhealth-checklist-archived-storieslist-epicslist-my-archived-storieslist-my-storieslist-objectiveslist-projectslist-stories-by-state-namelist-stories-by-statuslist-teamslist-workflowssearch-storiesupdate-storyupdate-story-statusAll tools have clearly distinct purposes. Create tools target different resources, and list tools are well-differentiated by filters (archived, assigned to me, by state, etc.). No two tools appear to do the same thing.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create-epic, list-stories-by-state-name). Even the deprecated tool uses the same pattern, ensuring predictable naming.
With 18 tools, the server covers the core Shortcut entities (epics, objectives, stories, workflows, teams) without being overwhelming. Each tool earns its place for standard project management operations.
The tool set lacks update operations for epics and objectives, and there are no delete capabilities for any resource. This leaves significant gaps in CRUD coverage, forcing agents to work around missing lifecycle support.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Shortcut project management. Create, update, search stories and manage workflows.
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for generating rough-draft project plans from natural-language prompts.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/idyll/shortcut-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
