Provides integration with Shortcut's project management platform, allowing AI assistants to interact with Shortcut data using an API token for authentication.
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 Server show me my open stories in the sprint"
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.
The MCP server for Shortcut.
See the official Windsurf docs for more information.
Open the Windsurf MCP Configuration Panel
Click Add custom server.
Add the following details and save the file:
{
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}
See the official Cursor docs for more information.
Open (or create) the mcp.json file (it should be in ~/.cursor/mcp.json or <project-root>/.cursor/mcp.json, but see Cursor docs for more details).
Add the following details and save the file:
{
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}See the official Claude Code docs for more information.
You can add a new MCP server from the Claude Code CLI. But modifying the json file directly is simpler!
Open the Claude Code configuration file (it should be in ~/.claude.json).
Find the projects > mcpServers section and add the following details and save the file:
{
"projects": {
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}
}Open your settings.json file. Instructions here
Add the following details and save the file:
"context_servers": {
"shortcut": {
"settings":{},
"command": {
"path": "<PATH/TO/NPX>",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}Related MCP server: Shortcut.com MCP Server
Before doing anything else, please make sure you are running the latest version!
If you run into problems using this MCP server, you have a couple of options:
You can also check the list of common issues below to see if there is a known solution already.
If you are using MISE for managing Node and NPM versions, you may encounter a "Client closed" error when trying to run the MCP server. Installing this extension into your IDE might help: https://github.com/hverlin/mise-vscode/.
npm installnpm run buildTo test your local development version of the MCP server rather than using the published package, follow these steps:
Build the project:
npm run buildCreate or modify your mcp.json file to reference your local build:
{
"mcpServers": {
"shortcut": {
"command": "node",
"args": [
"/path/to/your/local/mcp-server-shortcut/dist/index.js"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}Place this mcp.json file in one of the following locations:
For Cursor: In your home directory (~/.cursor/mcp.json) or in your project directory (.cursor/mcp.json)
For Windsurf: Use the MCP Configuration Panel to add the custom server
Restart your AI assistant (Cursor or Windsurf) to load the new configuration.
This allows you to instantly test changes to the MCP server without having to publish a new version.
Add an external link to a Shortcut story
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story | |
| externalLink | Yes | The external link URL to add |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool adds a link but doesn't clarify if this is a mutation (implied by 'Add'), what permissions are required, whether it's idempotent, or how it handles errors (e.g., invalid story ID or duplicate links). For a mutation tool with zero annotation coverage, this is a significant gap in 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?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. It earns its place by clearly stating the tool's function, making it easy for an agent to parse quickly. No fluff or redundancy is present.
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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like side effects, error handling, or return values, which are critical for safe invocation. The high schema coverage helps with inputs, but overall context for usage and outcomes is lacking.
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%, with clear descriptions for both parameters (storyPublicId and externalLink), so the schema does the heavy lifting. The description adds no additional meaning beyond what's in the schema, such as format examples or constraints like URL validation. Baseline 3 is appropriate when the schema fully documents parameters.
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 ('Add') and the resource ('external link to a Shortcut story'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'remove-external-link-from-story' and 'set-story-external-links' by focusing on a single addition operation. However, it doesn't specify if this adds to existing links or replaces them, which slightly limits differentiation.
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 like 'set-story-external-links' or 'remove-external-link-from-story'. It lacks context about prerequisites (e.g., story existence, permissions) or exclusions, leaving the agent to infer usage from tool names alone without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a story relationship to a story
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story | |
| relatedStoryPublicId | Yes | The public ID of the related story | |
| relationshipType | No | The type of relationship | relates to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the action without disclosing behavioral traits. It doesn't mention if this is a mutation (implied by 'Add'), what permissions are needed, whether relationships are bidirectional, or how errors are handled, leaving significant gaps in understanding the tool's behavior.
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 with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly without unnecessary elaboration.
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 complexity of a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits, usage context, and return values, failing to compensate for the missing structured data, which could lead to incorrect agent usage.
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%, providing clear documentation for all parameters. The description adds no additional meaning beyond the schema, such as explaining relationship semantics or constraints, so it meets the baseline but doesn't enhance parameter understanding.
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 ('Add') and resource ('story relationship to a story'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'update-story' or 'create-story' in terms of relationship-specific functionality, which prevents a perfect score.
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. It doesn't mention prerequisites (e.g., existing stories), exclusions, or compare to siblings like 'update-story' for relationship management, leaving the agent with insufficient context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a task to a story
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story | |
| taskDescription | Yes | The description of the task | |
| taskOwnerIds | No | Array of user IDs to assign as owners of the task |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action without behavioral details. It doesn't disclose permissions needed, whether the operation is idempotent, error handling, or what happens on success (e.g., task ID returned). For a mutation tool with zero annotation coverage, this is a significant gap in 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?
The description is a single, clear sentence with zero waste—it directly states the tool's purpose without fluff. It's appropriately sized and front-loaded, making it easy to parse quickly.
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 mutation tool with no annotations and no output schema, the description is incomplete. It doesn't cover behavioral aspects (e.g., side effects, return values), usage context, or how it integrates with sibling tools. Given the complexity of adding tasks and the lack of structured data, 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 the schema fully documents parameters (storyPublicId, taskDescription, taskOwnerIds). The description adds no meaning beyond the schema—it doesn't explain parameter relationships, constraints, or examples. Baseline 3 is appropriate as the schema does the heavy lifting.
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 'Add a task to a story' clearly states the action (add) and resource (task to story), but it's vague about scope and doesn't differentiate from sibling tools like 'create-story' or 'update-task'. It specifies what it does but lacks detail on how it fits within the broader context of story management.
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. It doesn't mention prerequisites (e.g., story must exist), exclusions, or how it relates to siblings like 'create-story' (for initial creation) or 'update-task' (for modifying existing tasks). The description alone offers no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Assign the current user as the owner of a story
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the action without behavioral details. It doesn't disclose whether this requires specific permissions, if it's reversible, what happens to the previous owner, or any side effects. For a mutation tool with zero annotation coverage, this 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 a single, efficient sentence that directly states the tool's purpose with no wasted words. It is appropriately front-loaded and earns its place by clearly conveying the core action.
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 mutation tool with no annotations and no output schema, the description is incomplete. It lacks information about behavioral traits, return values, error conditions, or integration with sibling tools. Given the complexity of ownership changes, more context is needed for effective use.
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%, with the single parameter 'storyPublicId' well-documented in the schema. The description adds no additional parameter semantics beyond implying the story is identified by its public ID, so it meets the baseline for high schema coverage.
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 ('Assign') and resource ('owner of a story'), specifying it applies to the current user. It distinguishes from sibling 'unassign-current-user-as-owner' by being the opposite operation, though it doesn't explicitly differentiate from other story-modification tools like 'update-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 is provided on when to use this tool versus alternatives like 'update-story' (which might also handle ownership changes) or 'unassign-current-user-as-owner'. The description implies usage for ownership assignment but lacks context about prerequisites, permissions, or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new document in Shortcut with a title and content. Returns the document's id, title, and app_url. Note: Use HTML markup for the content (e.g., , , , ) rather than Markdown.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | The title for the new document (max 256 characters) | |
| content | Yes | The content for the new document in HTML format (e.g., <p>Hello</p>, <h1>Title</h1>, <ul><li>Item</li></ul>) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses that the tool creates (a write operation) and returns specific fields (id, title, app_url), which is helpful. However, it doesn't mention permissions, rate limits, error conditions, or other behavioral traits like whether the document is immediately published or saved as draft.
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 efficiently structured in two sentences: the first states the purpose and return values, the second provides a critical usage note about HTML markup. Every sentence adds value with zero waste, and key information is 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?
For a creation tool with no annotations and no output schema, the description provides basic purpose and return values, but lacks details on permissions, error handling, or system behavior. It's minimally adequate given the simple two-parameter schema, but could be more complete for a mutation operation.
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 both parameters thoroughly. The description adds marginal value by reinforcing that content uses HTML markup, but doesn't provide additional semantic context beyond what's in the schema. Baseline 3 is appropriate when schema does the heavy lifting.
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 a new document'), specifies the resource ('in Shortcut'), and lists the key inputs ('with a title and content'). It distinguishes from sibling tools like 'create-story' or 'create-epic' by focusing specifically on documents, not stories or epics.
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 creating documents in Shortcut, but provides no explicit guidance on when to use this tool versus alternatives like 'create-story' or 'create-epic'. It mentions HTML markup requirements, which offers some contextual usage hint, but lacks explicit when/when-not instructions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Shortcut epic.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the epic | |
| owner | No | The user ID of the owner of the epic | |
| description | No | A description of the epic | |
| teamId | No | The ID of a team to assign the epic to |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states this is a creation tool, implying mutation, but doesn't address permissions, side effects, error conditions, or what the response looks like. For a mutation tool with zero annotation coverage, this is a significant gap in 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?
The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It's appropriately sized and front-loaded, making it easy for an agent to parse quickly.
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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't explain what happens after creation, potential constraints, or how it fits into the broader context of sibling tools. The agent lacks sufficient information to use this tool effectively beyond basic parameter passing.
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 schema description coverage is 100%, so the schema already documents all four parameters (name, owner, description, teamId) with clear descriptions. The tool description adds no additional parameter information beyond what's in the schema, which is acceptable given the high schema coverage, resulting in a baseline score 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 clearly states the action ('Create') and resource ('new Shortcut epic'), making the purpose immediately understandable. However, it doesn't differentiate this tool from other creation tools like create-document, create-iteration, or create-story, which would require mentioning what distinguishes an epic from those other entities.
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. It doesn't mention prerequisites (e.g., needing a team or owner), when not to use it, or how it relates to sibling tools like create-story or search-epics, 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.
Create a new Shortcut iteration
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the iteration | |
| startDate | Yes | The start date of the iteration in YYYY-MM-DD format | |
| endDate | Yes | The end date of the iteration in YYYY-MM-DD format | |
| teamId | No | The ID of a team to assign the iteration to | |
| description | No | A description of the iteration |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention permissions needed, whether this is a write operation that modifies data, what happens on success/failure, or any rate limits. 'Create' implies mutation, but the description lacks crucial behavioral details for a tool with no annotation coverage.
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 that communicates the core purpose without any wasted words. It's appropriately sized and front-loaded with the essential information.
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 creation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what a 'Shortcut iteration' is in this context, what happens after creation, or what the tool returns. The agent must rely entirely on the input schema and tool name without adequate contextual guidance.
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 all parameters are documented in the schema. The description adds no additional parameter information beyond what's already in the schema. According to scoring rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description.
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 ('new Shortcut iteration'), making the purpose immediately understandable. It doesn't distinguish from siblings like 'create-epic' or 'create-story', but the specific mention of 'iteration' provides adequate differentiation for this context.
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 like 'create-epic' or 'create-story'. It doesn't mention prerequisites, context, or any comparison with sibling tools, leaving the agent to infer usage solely from the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new Shortcut story. Name is required, and either a Team or Workflow must be specified:
If only Team is specified, we will use the default workflow for that team.
If Workflow is specified, it will be used regardless of Team. The story will be added to the default state for the workflow.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The name of the story. Required. | |
| description | No | The description of the story | |
| type | No | The type of the story | feature |
| owner | No | The user id of the owner of the story | |
| epic | No | The epic id of the epic the story belongs to | |
| iteration | No | The iteration id of the iteration the story belongs to | |
| team | No | The team ID or mention name of the team the story belongs to. Required unless a workflow is specified. | |
| workflow | No | The workflow ID to add the story to. Required unless a team is specified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly indicates this is a creation/mutation operation and describes the default state behavior ('The story will be added to the default state for the workflow'), which is valuable context. However, it doesn't mention permission requirements, rate limits, or what the response looks like, leaving some behavioral aspects unclear.
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 perfectly front-loaded with the core purpose, followed by essential usage rules. Every sentence earns its place with no wasted words. The bullet points efficiently clarify parameter relationships without unnecessary elaboration.
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 creation tool with no annotations and no output schema, the description does well by explaining the core creation logic and parameter relationships. However, it could be more complete by mentioning what the tool returns (e.g., the created story object) or any side effects beyond the stated default state behavior.
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?
With 100% schema description coverage, the schema already documents all 8 parameters thoroughly. The description adds some value by explaining the conditional logic between 'team' and 'workflow' parameters and clarifying the default workflow behavior, but doesn't provide additional semantic context beyond what's already in the schema descriptions.
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 specific action ('Create a new Shortcut story') and resource ('story'), distinguishing it from sibling tools like 'create-epic' or 'create-iteration'. It provides a complete verb+resource+scope statement that leaves no ambiguity about what this tool does.
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 explicitly states when to use this tool ('Create a new Shortcut story') and provides clear conditional logic for parameter usage ('Name is required, and either a Team or Workflow must be specified'). It distinguishes this from update operations and other creation tools by focusing specifically on story creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a comment on a story
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story | |
| text | Yes | The text of the comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Create' implies a write operation, it doesn't specify permissions required, whether comments are editable/deletable, rate limits, or what happens on success/failure. This leaves significant behavioral gaps 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 a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple creation tool and front-loads the essential information.
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 mutation tool with no annotations and no output schema, the description is insufficient. It doesn't address behavioral aspects like permissions, side effects, or response format. Given the complexity of creating content in what appears to be a project management system, more context about the operation's implications 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%, providing complete parameter documentation. The description adds no additional parameter semantics beyond what's in the schema (storyPublicId and text). This meets the baseline expectation when schema coverage is comprehensive.
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 target resource ('a comment on a story'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'create-story' or 'add-task-to-story' that also create content on stories, leaving some ambiguity about when to choose this specific tool.
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 multiple sibling tools that create or add content to stories (e.g., 'create-story', 'add-task-to-story', 'add-external-link-to-story'), there's no indication of when a comment is the appropriate choice versus other story modifications.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the active Shortcut iterations for the current user based on their team memberships
| Name | Required | Description | Default |
|---|---|---|---|
| teamId | No | The ID of a team to filter iterations by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the tool retrieves data based on team memberships, but doesn't disclose behavioral traits like whether it requires authentication, returns paginated results, includes rate limits, or what 'active' means (e.g., time-based criteria). This is a significant gap for a tool with potential complexity.
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 with zero waste. It front-loads the core purpose and includes key constraints (current user, team memberships), making it easy to parse quickly.
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 annotations and no output schema, the description is minimally adequate but lacks details on return values, error handling, or behavioral nuances. It covers the basic purpose but doesn't fully compensate for missing structured data, leaving gaps for an AI agent to infer usage.
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 optional 'teamId' parameter. The description adds context that iterations are filtered by the user's team memberships, implying 'teamId' further narrows this, but doesn't provide additional syntax or format details beyond what the schema offers.
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 ('Get') and resource ('active Shortcut iterations'), specifying they are for the current user based on team memberships. It distinguishes from siblings like 'get-iteration' (singular) and 'get-upcoming-iterations' (future-focused), but doesn't explicitly contrast with 'search-iterations' (which might allow broader filtering).
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 needing active iterations for the current user's teams, but doesn't explicitly state when to use this vs. alternatives like 'search-iterations' or 'get-upcoming-iterations'. No exclusions or prerequisites are mentioned, leaving some ambiguity about optimal tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current user
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Get' but doesn't clarify if this is a read-only operation, what authentication is required, or what the return format might be. For a tool with zero annotation coverage, this is a significant gap in 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?
The description is a single, efficient sentence with zero waste. It's front-loaded and appropriately sized for a simple tool, making it easy for an agent to parse quickly without extraneous details.
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's simplicity (0 parameters) but lack of annotations and output schema, the description is incomplete. It doesn't explain what 'current user' means in context (e.g., authenticated user) or what data is returned, leaving gaps for the agent to handle.
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 tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description doesn't add parameter details, which is appropriate, earning a baseline score of 4 for not introducing unnecessary 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 'Get the current user' clearly states the verb ('Get') and resource ('current user'), making the purpose immediately understandable. However, it doesn't differentiate from siblings like 'list-members' or 'get-team', which might also retrieve user-related information, so it doesn't reach the highest score.
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. It doesn't mention prerequisites (e.g., authentication context) or compare it to sibling tools like 'list-members' for broader user queries, leaving the agent to infer usage 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.
Get a Shortcut epic by public ID
| Name | Required | Description | Default |
|---|---|---|---|
| epicPublicId | Yes | The public ID of the epic to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic operation. It doesn't disclose behavioral traits such as error handling (e.g., what happens if the ID is invalid), response format, rate limits, or authentication requirements. This leaves significant gaps for an agent to understand how to use it effectively.
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 that front-loads the core purpose ('Get a Shortcut epic by public ID') with zero wasted words. It's appropriately sized for a simple retrieval tool with one parameter.
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's low complexity (one parameter, no output schema, no annotations), the description is minimally complete. It covers the basic purpose but lacks context on behavior, output, or integration with siblings. Without annotations or output schema, more detail on what the tool returns would be helpful for 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%, with the parameter 'epicPublicId' fully described in the schema. The description adds no additional meaning beyond what the schema provides (e.g., no context on ID format or sourcing). Baseline 3 is appropriate since the schema handles parameter documentation adequately.
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 ('Get') and resource ('a Shortcut epic'), specifying it's by 'public ID'. It distinguishes from siblings like 'search-epics' by focusing on retrieval of a single epic rather than searching. However, it doesn't explicitly contrast with 'get-story' or other get-* tools beyond the resource type.
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 you have a specific epic's public ID, as opposed to 'search-epics' for broader queries. However, it lacks explicit guidance on when to use this versus 'get-story' or other retrieval tools, and doesn't mention prerequisites like authentication or access rights.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Shortcut iteration by public ID
| Name | Required | Description | Default |
|---|---|---|---|
| iterationPublicId | Yes | The public ID of the iteration to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves an iteration but doesn't describe what happens if the ID is invalid (e.g., error behavior), whether it's a read-only operation (implied by 'Get' but not explicit), or any rate limits or authentication requirements. For a tool with zero annotation coverage, this leaves significant gaps in understanding its operational behavior.
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 that front-loads the core purpose without unnecessary words. Every element ('Get', 'Shortcut iteration', 'by public ID') earns its place by directly informing the tool's function. There is zero waste or redundancy.
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's simplicity (one required parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic 'what' but lacks context on error handling, return format, or integration with sibling tools. Without annotations or output schema, the agent must rely on the description and schema alone, which is sufficient for basic use but incomplete for robust operation.
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 schema description coverage is 100%, with the single parameter 'iterationPublicId' fully documented in the schema as 'The public ID of the iteration to get'. The description adds no additional semantic context beyond what the schema provides (e.g., format examples, ID sourcing, or uniqueness constraints). Since the schema does the heavy lifting, the 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 action ('Get') and resource ('a Shortcut iteration by public ID'), making the purpose immediately understandable. It distinguishes this tool from siblings like 'get-active-iterations' or 'get-iteration-stories' by specifying retrieval of a single iteration via its public ID. However, it doesn't explicitly contrast with 'search-iterations' or explain why one would use this exact lookup versus a search approach.
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. It doesn't mention prerequisites (e.g., needing a valid public ID), contrast with sibling tools like 'search-iterations' for broader queries, or indicate scenarios where this direct lookup is preferred over other retrieval methods. The agent must infer usage from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get stories in a specific iteration by iteration public ID
| Name | Required | Description | Default |
|---|---|---|---|
| iterationPublicId | Yes | The public ID of the iteration | |
| includeStoryDescriptions | No | Indicate whether story descriptions should be included. Including descriptions may take longer and will increase the size of the response. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions that including descriptions 'may take longer and will increase the size of the response' (which is actually in the schema, not the description), but the description itself lacks behavioral context about permissions needed, rate limits, pagination, or what format/structure the returned stories will have.
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 that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple retrieval tool and front-loads the core functionality.
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 retrieval tool with no annotations and no output schema, the description is insufficient. It doesn't explain what data is returned (story fields, format), whether there are pagination considerations, authentication requirements, or error conditions. The sibling tools include multiple story-related operations, making context about this specific retrieval method particularly important.
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 fully documents both parameters. The description doesn't add any meaningful parameter semantics beyond what's in the schema - it mentions 'by iteration public ID' which corresponds to the iterationPublicId parameter, but provides no additional context about valid values or usage patterns.
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 ('Get stories') and the target resource ('in a specific iteration by iteration public ID'), providing a specific verb+resource combination. However, it doesn't differentiate from sibling tools like 'search-stories' or 'get-story', which could retrieve similar data through different mechanisms.
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 like 'search-stories' or 'get-story'. It mentions the specific iteration requirement but doesn't explain why one would choose this tool over other story-retrieval methods available in the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Shortcut objective by public ID
| Name | Required | Description | Default |
|---|---|---|---|
| objectivePublicId | Yes | The public ID of the objective to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it's a read operation ('Get'), but doesn't cover permissions, error handling, rate limits, or response format. For a tool with no annotations, this leaves significant gaps in understanding its behavior.
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 with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly. Every word contributes directly to understanding the tool's 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?
Given no annotations and no output schema, the description is incomplete for a retrieval tool. It doesn't explain what an 'objective' is in this context, what data is returned, or any behavioral aspects like authentication needs. For a tool with one parameter but missing structured context, it should provide more guidance.
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%, with the single parameter 'objectivePublicId' fully documented in the schema. The description adds minimal value by mentioning 'by public ID', which aligns with the schema but doesn't provide additional context like format examples or constraints beyond what's in the schema. Baseline 3 is appropriate given high schema coverage.
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 ('Get') and resource ('a Shortcut objective'), specifying it's by 'public ID'. It distinguishes from siblings like 'search-objectives' by focusing on retrieval of a specific item rather than searching. However, it doesn't explicitly contrast with other 'get-' tools (e.g., 'get-story'), leaving some ambiguity.
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. It doesn't mention when to choose this over 'search-objectives' or other retrieval tools like 'get-story', nor does it specify prerequisites or exclusions. Usage is implied by the name but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find all stories that contain a specific external link
| Name | Required | Description | Default |
|---|---|---|---|
| externalLink | Yes | The external link URL to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool finds stories but doesn't mention any behavioral traits such as permissions required, rate limits, pagination, or what happens if no stories are found. This leaves significant gaps for an agent to understand how to use it effectively.
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, clear sentence that efficiently conveys the core functionality without any fluff. It's front-loaded with the essential action and resource, making it easy for an agent to parse quickly.
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 lack of annotations and output schema, the description is incomplete. It doesn't cover behavioral aspects like error handling or return format, and with siblings that might overlap, more context is needed to ensure the agent can use this tool correctly in practice.
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% description coverage, with the parameter 'externalLink' well-documented as 'The external link URL to search for.' The description adds no additional semantic context beyond this, such as examples or format nuances, so it meets the baseline for high schema coverage without extra value.
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's purpose: 'Find all stories that contain a specific external link.' It specifies the verb ('find'), resource ('stories'), and constraint ('contain a specific external link'). However, it doesn't explicitly differentiate from sibling tools like 'search-stories' or 'get-story', which might have overlapping functionality, preventing a perfect score.
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 siblings like 'search-stories' and 'get-story' that might retrieve stories in different ways, there's no indication of when this specific link-based search is preferred or what its limitations are, leaving usage ambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Shortcut story by public ID
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves a story but doesn't describe what information is returned, whether it's a read-only operation, potential error conditions, or any rate limits. For a retrieval tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves beyond its basic purpose.
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 that front-loads the essential information: 'Get a Shortcut story by public ID'. There is no wasted language, repetition, or unnecessary elaboration. Every word earns its place by contributing directly to understanding the tool's 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?
Given the lack of annotations and output schema, the description is incomplete for effective tool use. It doesn't explain what data is returned (e.g., story details, error formats), behavioral aspects like read-only nature, or how it differs from similar tools. For a retrieval tool in a context with multiple sibling tools, more contextual information is needed to guide the agent appropriately.
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% description coverage, with the single parameter 'storyPublicId' clearly documented as 'The public ID of the story to get'. The description adds no additional parameter information beyond what the schema provides, such as format examples or constraints. With high schema coverage, the baseline score of 3 is appropriate as the schema handles the parameter documentation adequately.
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 ('Get') and resource ('a Shortcut story by public ID'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'get-epic' or 'get-iteration', but the specificity of 'story' and 'public ID' provides adequate distinction. The description avoids tautology by not simply restating the tool name.
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. It doesn't mention sibling tools like 'search-stories' or 'get-stories-by-external-link' that might serve similar purposes, nor does it specify prerequisites or contexts where this tool is preferred. The agent must infer usage solely from the tool name and description without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a valid branch name for a specific story.
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public Id of the story |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Get' implies a read operation, but doesn't cover aspects like whether it requires authentication, rate limits, error handling, or what format the branch name returns (e.g., string pattern). This leaves significant gaps in understanding the tool's behavior.
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 that directly states the tool's purpose without unnecessary words. It's front-loaded and appropriately sized for a simple tool, making it easy to parse quickly.
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 annotations and no output schema, the description is incomplete. It doesn't explain what a 'valid branch name' entails (e.g., format, constraints) or the return value, which is critical for a tool with implied output complexity. For a read operation with potential behavioral nuances, more context 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%, with the single parameter 'storyPublicId' well-documented in the schema. The description adds no additional semantic context beyond implying it's for a 'specific story', which the schema already covers. This meets the baseline for high schema coverage without extra value.
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 'Get' and the resource 'valid branch name for a specific story', making the purpose understandable. However, it doesn't differentiate from sibling tools like 'get-story' or 'search-stories', which might also retrieve story-related information, leaving some ambiguity about its unique role.
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. It doesn't specify prerequisites, such as needing a story ID, or compare it to other get/search tools in the sibling list, leaving the agent to infer usage context without explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Shortcut team by public ID
| Name | Required | Description | Default |
|---|---|---|---|
| teamPublicId | Yes | The public ID of the team to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves a team but doesn't describe what information is returned, error conditions (e.g., invalid ID), authentication needs, rate limits, or whether it's a read-only operation. For a tool with zero annotation coverage, this is a significant gap in 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?
The description is a single, efficient sentence that front-loads the core purpose without any wasted words. It's appropriately sized for a simple retrieval tool, making it easy to parse quickly.
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 annotations, no output schema, and a simple parameter with full schema coverage, the description is incomplete. It doesn't explain what data is returned, error handling, or behavioral traits, which are crucial for a retrieval tool. The conciseness comes at the cost of missing contextual details needed for effective use.
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 description adds that the parameter is for getting a team by public ID, but the input schema already fully documents the single parameter 'teamPublicId' with 100% coverage. No additional semantic details (e.g., format examples, where to find the ID) are provided, so it doesn't add value beyond the schema, resulting in the 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 the action ('Get') and resource ('a Shortcut team'), specifying it's by public ID. It distinguishes from siblings like 'list-teams' by focusing on a single team retrieval rather than listing multiple teams. However, it doesn't explicitly contrast with other get-* tools like 'get-story' or 'get-epic' beyond the resource type.
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 you need a specific team by its public ID, but doesn't provide explicit guidance on when to use this versus alternatives like 'list-teams' for browsing or other get-* tools for different resources. No exclusions or prerequisites are mentioned, leaving usage context somewhat implied rather than clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the upcoming Shortcut iterations for the current user based on their team memberships
| Name | Required | Description | Default |
|---|---|---|---|
| teamId | No | The ID of a team to filter iterations by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions the tool retrieves data ('Get') but doesn't disclose behavioral traits such as whether it requires authentication, rate limits, pagination, error handling, or the format of returned iterations. The description is minimal and lacks crucial operational details.
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 that front-loads the core purpose without unnecessary words. It directly communicates the tool's function and scope, making it easy to parse and understand quickly.
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 annotations and no output schema, the description is incomplete for a tool that likely returns complex iteration data. It doesn't explain what 'upcoming' means (e.g., time frame), the structure of returned iterations, or any dependencies like user authentication. For a read operation with potential nuances, more context 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?
The input schema has 100% description coverage, with one optional parameter 'teamId' documented as 'The ID of a team to filter iterations by'. The description adds no additional parameter semantics beyond this, so it meets the baseline of 3 where the schema does the heavy lifting.
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 ('Get') and resource ('upcoming Shortcut iterations'), specifying scope ('for the current user based on their team memberships'). It distinguishes from siblings like 'get-active-iterations' by focusing on 'upcoming' iterations, though it doesn't explicitly contrast with 'search-iterations' or 'get-iteration'.
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 context ('for the current user based on their team memberships') but doesn't explicitly state when to use this tool versus alternatives like 'search-iterations' or 'get-active-iterations'. It provides some guidance by specifying the user scope but lacks clear exclusions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Shortcut workflow by public ID
| Name | Required | Description | Default |
|---|---|---|---|
| workflowPublicId | Yes | The public ID of the workflow to get |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states 'Get' which implies a read operation, but doesn't disclose behavioral traits like authentication needs, rate limits, error conditions, or what happens if the ID doesn't exist. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
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 that front-loads the core purpose ('Get a Shortcut workflow') and adds necessary specificity ('by public ID'). There is zero wasted verbiage, making it appropriately sized and well-structured for quick comprehension.
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 annotations, no output schema, and a simple single-parameter input, the description is incomplete. It doesn't explain what 'Get' returns (e.g., workflow details, error formats) or address behavioral aspects like permissions or limitations. For a tool with zero structured coverage beyond input schema, the description should do more to compensate.
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%, with the single parameter 'workflowPublicId' fully documented in the schema as 'The public ID of the workflow to get'. The description adds no additional meaning beyond this, simply restating 'by public ID'. With high schema coverage, the baseline is 3 even without extra param info in the description.
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 ('Get') and resource ('a Shortcut workflow'), making the purpose immediately understandable. It specifies retrieval by 'public ID', which distinguishes it from other retrieval methods. However, it doesn't explicitly differentiate from sibling tools like 'list-workflows' or 'get-story', which would require a 5.
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 like 'list-workflows' for browsing or 'get-story' for other entity types. It mentions 'by public ID' which implies a prerequisite (knowing the ID), but offers no explicit when/when-not instructions or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all members
| 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 carries the full burden. 'Get all members' implies a read-only operation, but it doesn't disclose behavioral traits such as pagination, rate limits, authentication needs, or what 'all' entails (e.g., scope, limits). This leaves significant gaps for a tool with no annotation coverage.
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 ('Get all members')—just three words—with no wasted language. It's front-loaded and efficiently communicates the core purpose without unnecessary elaboration.
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 complexity (a list operation with no parameters) and lack of annotations and output schema, the description is incomplete. It doesn't explain return values, scope of 'members', or behavioral aspects, making it inadequate for full understanding despite the simple input schema.
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 tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The baseline for 0 parameters is 4, as the description doesn't need to compensate for any missing param info.
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 'Get all members' clearly states the verb ('Get') and resource ('members'), but lacks specificity about what 'members' refers to (e.g., team members, organization members) and doesn't distinguish it from sibling tools like 'get-team' or 'list-teams'. It's vague but functional.
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 like 'get-team' or 'list-teams', nor any context about prerequisites or exclusions. The description alone offers no usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Shortcut teams
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a list operation (implied read-only) but doesn't mention pagination, sorting, rate limits, authentication needs, or what 'all' means in practice. This leaves significant behavioral gaps for a tool that likely returns multiple items.
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 that states exactly what the tool does with zero wasted words. It's front-loaded and appropriately sized for a simple list 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?
Given no annotations, no output schema, and multiple sibling tools, the description is insufficiently complete. It doesn't explain what data is returned (team objects? just names?), how results are structured, or how this differs from related tools like 'get-team'. For a list operation in a collaborative tool context, more context 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?
The tool has zero parameters with 100% schema description coverage, so the schema already fully documents the input. The description appropriately doesn't add parameter information, maintaining focus on the tool's purpose. Baseline for zero parameters is 4.
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 all') and resource ('Shortcut teams'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get-team' (singular) or 'list-members' (different resource), which prevents a perfect score.
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 like 'get-team' (singular team) or 'list-members' (team members). There's no mention of prerequisites, context, or exclusions, leaving usage entirely implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Shortcut workflows
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic action. It doesn't disclose behavioral traits like whether this returns all workflows at once, if there's pagination, what permissions are needed, or the format of returned data. For a list operation with zero annotation coverage, this 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 a single, efficient sentence with zero waste—'List all Shortcut workflows'—front-loading the key information. Every word earns its place, making it easy to parse quickly.
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 lack of annotations and output schema, the description is incomplete. It doesn't explain what 'list all' entails (e.g., pagination, sorting, or data format), which is critical for a list tool. With no structured fields to compensate, the description should provide more behavioral context.
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 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't mention parameters, focusing instead on the tool's purpose, which aligns with the schema's simplicity.
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 ('List') and resource ('Shortcut workflows'), making the purpose immediately understandable. It doesn't differentiate from siblings like 'get-workflow' or 'search-stories', but it's specific enough to avoid confusion with unrelated tools.
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 like 'get-workflow' (for a single workflow) or 'search-stories' (for filtered results). It simply states what it does without context about use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove an external link from a Shortcut story
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story | |
| externalLink | Yes | The external link URL to remove |
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 disclosure. It states the tool performs a removal action, implying mutation, but lacks critical details: whether this requires specific permissions, if the operation is reversible, what happens on success/failure, or any rate limits. For a mutation tool with zero annotation coverage, this is a significant gap in 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?
The description is a single, efficient sentence that front-loads the core action and target. There's no wasted language, repetition, or unnecessary elaboration. It directly communicates the tool's function without ambiguity, making it highly concise and well-structured.
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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, side effects, or error handling, nor does it explain what the tool returns. For a tool that modifies data, more context is needed to ensure safe and correct usage by an agent.
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%, with both parameters ('storyPublicId' and 'externalLink') well-documented in the schema. The description doesn't add any parameter-specific details beyond what the schema provides (e.g., it doesn't clarify format constraints or examples). According to guidelines, when schema coverage is high (>80%), the baseline score is 3 even without param info in the description.
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 ('Remove') and target resource ('an external link from a Shortcut story'), making the purpose immediately understandable. It distinguishes from siblings like 'add-external-link-to-story' by specifying removal rather than addition. However, it doesn't explicitly contrast with other modification tools like 'set-story-external-links' or 'update-story', which prevents a perfect score.
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. It doesn't mention prerequisites (e.g., the link must exist), exclusions, or comparisons to sibling tools like 'set-story-external-links' (which might manage multiple links) or 'update-story' (which might handle broader story edits). Without this context, agents must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Shortcut epics.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Find only epics with the specified public ID | |
| name | No | Find only epics matching the specified name | |
| description | No | Find only epics matching the specified description | |
| state | No | Find only epics matching the specified state | |
| objective | No | Find only epics matching the specified objective | |
| owner | No | Find entities where the owner match the specified user. This must either be the user's mention name or the keyword "me" for the current user. | |
| requester | No | Find entities where the requester match the specified user. This must either be the user's mention name or the keyword "me" for the current user. | |
| team | No | Find only epics matching the specified team. Should be a team's mention name. | |
| comment | No | Find only epics matching the specified comment | |
| isUnstarted | No | Find only entities that are unstarted when true, or only entities that are not unstarted when false. | |
| isStarted | No | Find only entities that are started when true, or only entities that are not started when false. | |
| isDone | No | Find only entities that are completed when true, or only entities that are not completed when false. | |
| isArchived | No | Find only entities that are archived when true, or only entities that are not archived when false. | |
| isOverdue | No | Find only entities that are overdue when true, or only entities that are not overdue when false. | |
| hasOwner | No | Find only entities that have an owner when true, or only entities that do not have an owner when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasComment | No | Find only entities that have a comment when true, or only entities that do not have a comment when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasDeadline | No | Find only entities that have a deadline when true, or only entities that do not have a deadline when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasLabel | No | Find only entities that have a label when true, or only entities that do not have a label when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| created | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| updated | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| completed | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| due | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but fails completely. It doesn't indicate whether this is a read-only operation, what permissions are required, how results are returned (e.g., pagination, format), or any rate limits. The single sentence offers no behavioral context beyond the basic action implied by 'Find'.
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 with just three words, front-loading the core action. There's zero wasted language or redundancy, making it efficient to parse, though this brevity comes at the cost of completeness.
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 complex search tool with 22 parameters, no annotations, and no output schema, the description is severely inadequate. It doesn't explain the search behavior (e.g., filtering logic, result format), usage context, or relationship to other tools, leaving significant gaps despite the comprehensive parameter schema.
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%, meaning all 22 parameters are well-documented in the input schema with detailed descriptions. The tool description adds no parameter information beyond what's already in the schema, so it meets the baseline score of 3 for high schema coverage without compensating value.
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 'Find Shortcut epics' is a tautology that essentially restates the tool name 'search-epics' without adding meaningful specificity. It lacks a clear verb+resource distinction and doesn't differentiate from sibling tools like 'get-epic' or 'search-stories', providing minimal guidance on what this tool uniquely does.
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 absolutely no guidance on when to use this tool versus alternatives. It doesn't mention any context, prerequisites, or exclusions, nor does it reference sibling tools like 'get-epic' (for single epics) or 'search-stories' (for different entity types), leaving the agent with no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Shortcut iterations.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Find only iterations with the specified public ID | |
| name | No | Find only iterations matching the specified name | |
| description | No | Find only iterations matching the specified description | |
| state | No | Find only iterations matching the specified state | |
| team | No | Find only iterations matching the specified team. This can be a team ID or mention name. | |
| created | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| updated | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| startDate | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| endDate | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states 'Find Shortcut iterations' without disclosing behavioral traits. It doesn't mention whether this is a read-only operation, what permissions are needed, how results are returned (pagination, format), rate limits, or error conditions. The description is too minimal for a search tool with 9 parameters.
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 with zero waste. It's appropriately sized for a search tool where parameters are well-documented in the schema, though it could benefit from more context given the lack of annotations.
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 search tool with 9 parameters, no annotations, and no output schema, the description is incomplete. It doesn't explain what 'Shortcut iterations' are, how results are structured, whether all parameters are optional, or how to interpret empty results. The schema handles parameter details well, but the description lacks necessary context for effective tool selection.
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 all 9 parameters thoroughly with descriptions, patterns, and enums. The description adds no parameter semantics beyond the name 'search-iterations', which implies filtering but doesn't explain parameter interactions or default behavior when no parameters are provided.
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 'Find Shortcut iterations' clearly states the verb ('Find') and resource ('Shortcut iterations'), but it's vague about scope and doesn't differentiate from sibling tools like 'get-active-iterations' or 'get-upcoming-iterations'. It doesn't specify whether this searches all iterations or has specific filtering behavior beyond what parameters imply.
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 like 'get-active-iterations', 'get-upcoming-iterations', or 'get-iteration'. The description doesn't mention prerequisites, context, or exclusions. Usage is implied through parameters but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Shortcut objectives.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Find objectives matching the specified id | |
| name | No | Find objectives matching the specified name | |
| description | No | Find objectives matching the specified description | |
| state | No | Find objectives matching the specified state | |
| owner | No | Find entities where the owner match the specified user. This must either be the user's mention name or the keyword "me" for the current user. | |
| requester | No | Find entities where the requester match the specified user. This must either be the user's mention name or the keyword "me" for the current user. | |
| team | No | Find objectives matching the specified team. Should be a team mention name. | |
| isUnstarted | No | Find only entities that are unstarted when true, or only entities that are not unstarted when false. | |
| isStarted | No | Find only entities that are started when true, or only entities that are not started when false. | |
| isDone | No | Find only entities that are completed when true, or only entities that are not completed when false. | |
| isArchived | No | Find only entities that are archived when true, or only entities that are not archived when false. | |
| hasOwner | No | Find only entities that have an owner when true, or only entities that do not have an owner when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| created | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| updated | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| completed | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but provides none. It doesn't indicate whether this is a read-only operation, what permissions might be required, whether results are paginated, what format results return, or any rate limits. The single sentence 'Find Shortcut objectives' reveals nothing about the tool's behavior beyond the obvious.
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 maximally concise with a single three-word sentence that gets straight to the point. There's zero wasted verbiage or unnecessary elaboration. While it's severely under-specified, it's perfectly structured for its minimal content.
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 search tool with 15 parameters, no annotations, and no output schema, the description is completely inadequate. It doesn't explain what 'objectives' are in the Shortcut context, what fields are searchable, whether this is a simple or advanced search, what the return format looks like, or any behavioral characteristics. The description fails to provide the necessary context for an agent to use this tool effectively.
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 schema description coverage is 100%, so the schema already documents all 15 parameters thoroughly with detailed descriptions and examples. The description adds no parameter information whatsoever, not even mentioning that filtering parameters exist. However, with complete schema coverage, the baseline score of 3 is appropriate since the schema does the heavy lifting.
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 'Find Shortcut objectives' is a tautology that essentially restates the tool name 'search-objectives'. It provides no specific verb beyond 'find' and doesn't distinguish this search tool from other search tools on the server like 'search-epics', 'search-iterations', or 'search-stories'. The purpose is vague about what kind of search this performs.
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 absolutely no guidance about when to use this tool versus alternatives. There are multiple search tools on the server (search-objectives, search-epics, search-iterations, search-stories), but the description doesn't help an agent understand when to search for objectives versus other entity types. No context about prerequisites or typical use cases is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find Shortcut stories.
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | Find only stories with the specified public ID | |
| name | No | Find only stories matching the specified name | |
| description | No | Find only stories matching the specified description | |
| comment | No | Find only stories matching the specified comment | |
| type | No | Find only stories of the specified type | |
| estimate | No | Find only stories matching the specified estimate | |
| branch | No | Find only stories matching the specified branch | |
| commit | No | Find only stories matching the specified commit | |
| pr | No | Find only stories matching the specified pull request | |
| project | No | Find only stories matching the specified project | |
| epic | No | Find only stories matching the specified epic | |
| objective | No | Find only stories matching the specified objective | |
| state | No | Find only stories matching the specified state | |
| label | No | Find only stories matching the specified label | |
| owner | No | Find entities where the owner match the specified user. This must either be the user's mention name or the keyword "me" for the current user. | |
| requester | No | Find entities where the requester match the specified user. This must either be the user's mention name or the keyword "me" for the current user. | |
| team | No | Find only stories matching the specified team. This can be a team mention name or team name. | |
| skillSet | No | Find only stories matching the specified skill set | |
| productArea | No | Find only stories matching the specified product area | |
| technicalArea | No | Find only stories matching the specified technical area | |
| priority | No | Find only stories matching the specified priority | |
| severity | No | Find only stories matching the specified severity | |
| isDone | No | Find only entities that are completed when true, or only entities that are not completed when false. | |
| isStarted | No | Find only entities that are started when true, or only entities that are not started when false. | |
| isUnstarted | No | Find only entities that are unstarted when true, or only entities that are not unstarted when false. | |
| isUnestimated | No | Find only entities that are unestimated when true, or only entities that are not unestimated when false. | |
| isOverdue | No | Find only entities that are overdue when true, or only entities that are not overdue when false. | |
| isArchived | No | Find only entities that are archived when true, or only entities that are not archived when false. | |
| isBlocker | No | Find only entities that are blocking when true, or only entities that are not blocking when false. | |
| isBlocked | No | Find only entities that are blocked when true, or only entities that are not blocked when false. | |
| hasComment | No | Find only entities that have a comment when true, or only entities that do not have a comment when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasLabel | No | Find only entities that have a label when true, or only entities that do not have a label when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasDeadline | No | Find only entities that have a deadline when true, or only entities that do not have a deadline when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasOwner | No | Find only entities that have an owner when true, or only entities that do not have an owner when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasPr | No | Find only entities that have a pr when true, or only entities that do not have a pr when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasCommit | No | Find only entities that have a commit when true, or only entities that do not have a commit when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasBranch | No | Find only entities that have a branch when true, or only entities that do not have a branch when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasEpic | No | Find only entities that have an epic when true, or only entities that do not have an epic when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasTask | No | Find only entities that have a task when true, or only entities that do not have a task when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| hasAttachment | No | Find only entities that have an attachment when true, or only entities that do not have an attachment when false. Example: hasOwner: true will find stories with an owner, hasOwner: false will find stories without an owner. | |
| created | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| updated | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| completed | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). | |
| due | No | The date in "YYYY-MM-DD" format, or one of the keywords: "yesterday", "today", "tomorrow", or a date range in the format "YYYY-MM-DD..YYYY-MM-DD". The date range can also be open ended by using "*" for one of the bounds. Examples: "2023-01-01", "today", "2023-01-01..*" (from Jan 1, 2023 to any future date), "*.2023-01-31" (any date up to Jan 31, 2023), "today..*" (from today onwards), "*.yesterday" (any date up to yesterday). The keywords cannot be used to calculate relative dates (e.g. the following are not valid: "today-1" or "tomorrow+1"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure but offers none. It doesn't indicate whether this is a read-only operation, whether it requires authentication, what the output format might be, whether there are rate limits, or how results are returned (e.g., pagination). For a search tool with 44 parameters, this lack of behavioral context is a significant gap that leaves the agent guessing about important operational characteristics.
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 at just three words. While this represents under-specification in terms of content, it's not verbose or poorly structured. Every word earns its place by identifying the action ('Find'), the platform ('Shortcut'), and the resource ('stories'). There's no wasted language or unnecessary complexity.
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 complexity (44 parameters, no annotations, no output schema), the description is woefully incomplete. It doesn't explain what 'Find' means operationally, what the return format is, whether there are limitations or constraints, or how this tool differs from other story-accessing tools. For a search tool with extensive filtering capabilities, the description should provide more context about the search behavior and results.
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 schema description coverage is 100%, with every parameter having a detailed description in the input schema. The tool description adds no additional parameter information beyond what's already documented in the schema. According to the scoring rules, when schema_description_coverage is high (>80%), the baseline is 3 even with no param info in the description, which applies here.
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 'Find Shortcut stories' is a tautology that essentially restates the tool name 'search-stories' with the platform name 'Shortcut' added. It doesn't specify what 'find' means operationally (search, filter, retrieve), nor does it distinguish this tool from other story-related tools like 'get-story' or 'get-stories-by-external-link' among the siblings. The purpose is vague beyond the basic concept of finding 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 description provides no guidance on when to use this tool versus alternatives. There are multiple sibling tools for accessing stories (e.g., 'get-story', 'get-stories-by-external-link', 'get-iteration-stories'), but the description doesn't indicate that this is a general search/filter tool versus those more specific retrieval methods. No context about prerequisites, limitations, or appropriate use cases is mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Replace all external links on a story with a new set of links
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story | |
| externalLinks | Yes | Array of external link URLs to set (replaces all existing links) |
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 disclosure. It states 'replaces all existing links,' which implies a destructive mutation, but doesn't cover critical aspects like permissions needed, whether changes are reversible, rate limits, or what happens if the operation fails. For a mutation tool with zero annotation coverage, this is a significant gap in 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?
The description is a single, efficient sentence that front-loads the core action ('Replace all external links') and includes essential context ('with a new set of links'). There is no wasted verbiage, making it highly concise and well-structured for quick understanding.
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 this is a mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on behavioral traits (e.g., side effects, error handling), return values, and usage context relative to siblings. While the schema covers parameters well, the overall context for safe and effective tool invocation is insufficient.
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%, with clear descriptions for both parameters (storyPublicId and externalLinks). The description adds minimal value beyond the schema by emphasizing that externalLinks 'replaces all existing links,' but doesn't provide additional context like format examples or constraints. Baseline 3 is appropriate as the schema does the heavy lifting.
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 ('Replace all external links') and resource ('on a story'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'add-external-link-to-story' or 'remove-external-link-from-story' beyond the 'replace all' phrasing, which is implied but not stated as a distinction.
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. It doesn't mention when to choose this over 'add-external-link-to-story' for adding links or 'update-story' for broader updates, nor does it specify prerequisites or exclusions, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unassign the current user as the owner of a story
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It implies a mutation (unassigning ownership) but doesn't disclose behavioral aspects like permissions needed, whether this is reversible, side effects, or error conditions. For a mutation tool with zero annotation coverage, this is inadequate.
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, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it highly efficient and easy to parse.
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 mutation tool with no annotations and no output schema, the description is incomplete. It lacks details on permissions, side effects, return values, or error handling, which are critical for safe and effective use by an AI agent.
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%, with the single parameter 'storyPublicId' fully documented in the schema. The description doesn't add any parameter-specific details beyond what the schema provides, so it meets the baseline for high schema coverage.
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 ('unassign') and resource ('owner of a story') with specificity about the current user. It distinguishes from its sibling 'assign-current-user-as-owner' by indicating the opposite operation, though it doesn't explicitly mention this distinction.
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 like 'update-story' for ownership changes, or prerequisites such as requiring the current user to already be the owner. The description only states what it does, not when it's appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing Shortcut story. Only provide fields you want to update. The story public ID will always be included in updates.
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story to update | |
| name | No | The name of the story | |
| description | No | The description of the story | |
| type | No | The type of the story | |
| epic | No | The epic id of the epic the story belongs to, or null to unset | |
| estimate | No | The point estimate of the story, or null to unset | |
| iteration | No | The iteration id of the iteration the story belongs to, or null to unset | |
| owner_ids | No | Array of user UUIDs to assign as owners of the story | |
| workflow_state_id | No | The workflow state ID to move the story to | |
| labels | No | Labels to assign to the story |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It hints at a partial update behavior ('Only provide fields you want to update') and notes that the story public ID is always included, but it doesn't cover critical aspects like required permissions, whether updates are reversible, rate limits, or what the response looks like. For a mutation tool with zero annotation coverage, this 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 concise and front-loaded with key information in two sentences, with no wasted words. It efficiently communicates the core action and a constraint, though it could be slightly more structured by explicitly separating usage notes from behavioral details.
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 complexity (10 parameters, mutation operation) and lack of annotations and output schema, the description is incomplete. It should cover more behavioral aspects like error handling, response format, or prerequisites. For a tool with this level of complexity and no structured support, the description falls short of providing adequate context.
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 all parameters thoroughly. The description adds minimal value beyond the schema by implying partial updates and the mandatory inclusion of 'storyPublicId', but it doesn't provide additional syntax, format details, or usage examples. Baseline 3 is appropriate when the schema does the heavy lifting.
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 resource ('existing Shortcut story'), making the purpose evident. However, it doesn't explicitly differentiate from sibling tools like 'create-story' or 'update-task', which would require mentioning it's for modifying existing stories specifically rather than creating new ones or updating other entities.
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 minimal guidance: it mentions that only fields to update should be provided and that the story public ID is always included. However, it lacks explicit when-to-use instructions, such as when to choose this over 'create-story' for new stories or how it relates to other update tools like 'update-task'. No alternatives or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a task in a story
| Name | Required | Description | Default |
|---|---|---|---|
| storyPublicId | Yes | The public ID of the story | |
| taskPublicId | Yes | The public ID of the task | |
| taskDescription | No | The description of the task | |
| taskOwnerIds | No | Array of user IDs to assign as owners of the task | |
| isCompleted | No | Whether the task is completed or not |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Update a task in a story' implies a mutation operation but doesn't specify what permissions are required, whether changes are reversible, what happens to existing task data not mentioned in parameters, or what the response looks like. For a mutation tool with zero annotation coverage, this leaves significant behavioral questions unanswered.
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 that gets straight to the point with zero wasted words. It's appropriately sized for a tool with good schema documentation and follows a clear subject-verb-object structure that's immediately comprehensible.
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 mutation tool with 5 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't address important contextual aspects like error conditions, what happens when only required parameters are provided, whether partial updates are supported, or what the tool returns. The combination of mutation operation, multiple parameters, and lack of structured metadata requires more descriptive context.
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 all parameters are documented in the schema itself. The description doesn't add any meaningful parameter semantics beyond what's already in the schema descriptions. It doesn't explain relationships between parameters, provide examples, or clarify edge cases. The baseline of 3 is appropriate when the schema does the heavy lifting.
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 a task in a story' clearly states the verb ('update') and resource ('task in a story'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'add-task-to-story' or 'update-story', which would require more specificity about what distinguishes this particular update operation.
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 sibling tools like 'add-task-to-story', 'update-story', and 'assign-current-user-as-owner', there's no indication of when this specific task update operation is appropriate versus other modification tools. No prerequisites, exclusions, or alternative suggestions are mentioned.
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.
v1.0.0add-external-link-to-story2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseadd-relation-to-story2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseadd-task-to-story2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseassign-current-user-as-owner2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falsecreate-document2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falsecreate-epic2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falsecreate-iteration2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falsecreate-story2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falsecreate-story-comment2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-active-iterations2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-epic2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-iteration2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-iteration-stories2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-objective2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-stories-by-external-link2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-story2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-story-branch-name2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-team2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-upcoming-iterations2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseget-workflow2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseremove-external-link-from-story2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falsesearch-epics2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falsesearch-iterations2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falsesearch-objectives2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falsesearch-stories2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseset-story-external-links2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseunassign-current-user-as-owner2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseupdate-story2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseupdate-task2 fields changedInput schema / $schemaAdded value: +"http://json-schema.org/draft-07/schema#"Input schema / additionalPropertiesAdded value: +falseadd-external-link-to-storyadd-relation-to-storyadd-task-to-storyassign-current-user-as-ownercreate-documentcreate-epiccreate-iterationcreate-storycreate-story-commentget-active-iterationsget-current-userget-epicget-iterationget-iteration-storiesget-objectiveget-stories-by-external-linkget-storyget-story-branch-nameget-teamget-upcoming-iterationsget-workflowlist-memberslist-teamslist-workflowsremove-external-link-from-storysearch-epicssearch-iterationssearch-objectivessearch-storiesset-story-external-linksunassign-current-user-as-ownerupdate-storyupdate-taskEach tool has a clearly distinct purpose targeting specific resources and actions in Shortcut, such as stories, epics, iterations, and users. There is no significant overlap; for example, 'create-story' and 'update-story' are distinct, and 'add-external-link-to-story' and 'set-story-external-links' serve different functions (add vs. replace).
Tool names follow a consistent verb-object pattern with hyphens (e.g., 'create-story', 'get-iteration'), making them readable and predictable. Minor deviations exist, such as 'assign-current-user-as-owner' being more verbose, but overall, the naming is highly consistent across the set.
With 33 tools, the count is borderline high for a project management server, potentially overwhelming for agents. While it covers many operations, it might be slightly heavy compared to typical well-scoped servers (3-15 tools), though not extreme.
The tool set provides comprehensive CRUD and lifecycle coverage for Shortcut's domain, including stories, epics, iterations, documents, and users. It supports creation, retrieval, updating, deletion (via removal tools), and search operations, with no obvious gaps for core workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Share one project context across ChatGPT, Claude, Telegram and any MCP client.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ampcome-mcps/shortcut-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
