Shortcut MCP Server

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.0.0
Disambiguation4/5
Most tools are clearly distinct by resource and action (e.g., list_story_comments vs list_epic_comments). However, generic update_story overlaps with transition_story_state and add_story_label, which could cause misselection.
Naming Consistency5/5
All tools follow a strict snake_case verb_noun pattern: list/get for reads, create/update/delete for writes, and resource-specific nouns. Even bulk operations and transition_story_state fit the pattern, with no mixed conventions.
Tool Count1/5
With 73 tools, this server far exceeds the 50+ extreme threshold. The massive surface is likely to overwhelm agents and create unnecessary selection overhead, despite each tool potentially having a specific purpose.
Completeness4/5
The tool set provides comprehensive CRUD coverage for stories, epics, projects, iterations, milestones, labels, linked files, and comments, plus search and bulk operations. Minor gaps include no update/delete for epic comments and no remove_epic_label.
Average 3.2/5 across 73 of 73 tools scored. Lowest: 2.1/5.
See the Tool Scores section below for per-tool breakdowns.
- No community issues in the last 6 months
- 0 commits in the last 12 weeks
- No stable releases found
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
Add a LICENSE file by following GitHub's guide. Once GitHub recognizes the license, the system will automatically detect it within a few hours.
If the license does not appear after some time, you can manually trigger a new scan using the MCP server admin interface.
MCP servers without a LICENSE cannot be installed.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
Add a glama.json file to provide metadata about your server.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits, but it says only 'Create a new label in Shortcut.' It does not mention that the 'confirm' parameter must be CONFIRM_WRITE, the existence of dry_run, idempotency, error conditions, or any side effects. This is a significant gap 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short (one sentence), but it is under-specified rather than concise. It adds no information beyond the tool name and title, making it an ineffective use of the description slot.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no output schema, and no annotations, the description is drastically incomplete. It fails to mention the required 'name' field, the confirm/dry_run mechanism, the color format, or any return value. This is wholly inadequate for a tool with moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description does not compensate. It provides no explanation of the 'name', 'external_id', 'dry_run', or 'description' parameters. The schema itself only describes 'color' and 'confirm', leaving most parameter semantics unexplained anywhere.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 ('a new label') in the Shortcut domain. It is distinct from sibling tools like update_label and delete_label, though it doesn't explicitly differentiate from add_story_label beyond the create semantics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not indicate when to use this tool versus alternatives such as update_label or add_story_label, nor does it mention any prerequisites or context for creating a label.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only restates the tool's name. It omits the required confirm=CONFIRM_WRITE behavior, dry_run support, and any side effects or permission requirements, making it nearly as opaque as no description at all.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise, but it is severely under-specified for a tool with seven parameters and no annotations. This is not meaningful conciseness; it is absent specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is completely inadequate for this tool's complexity. It lacks any information about return values, required fields, team/workspace context, confirmation requirements, or how it relates to other project operations. Without output schema or annotations, the agent has almost no guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description provides no parameter information, and schema description coverage is only 29%. Since the description must compensate for the poorly documented schema, the complete absence of parameter semantics is a critical failure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and names the exact resource 'project' in Shortcut. This clearly distinguishes it from sibling tools that create epics, milestones, stories, or other entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance about when to use this tool versus alternatives. It simply states what it does without mentioning prerequisites, exclusions, or comparing with other create tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
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 only states 'Update a label in Shortcut' without mentioning mutability, the required confirm safety parameter, dry_run support, reversibility, or any side effects. This is a significant gap 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but under-specifies the operation. It prioritizes brevity over usefulness, omitting any structural detail about inputs or behavior, and reads more like a placeholder than a deliberate documentation choice.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter mutation tool with no annotations and no output schema, this description is wholly inadequate. It lacks field explanations, safety behavior, and context about update semantics, making it impossible for an agent to invoke correctly without additional information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14% (only 'confirm' has a description), and the tool description adds nothing about the seven parameters. It does not explain name, color, archived, description, or label_id semantics, so the agent cannot accurately map inputs to intended effects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 'label', making the core action unambiguous. However, it does not differentiate this tool from sibling operations like create_label or delete_label beyond the verb, and it does not mention the specific fields involved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as create_label or delete_label. The description gives no context, prerequisites, or exclusions, leaving the agent without directional information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations to convey safety or side effects, the description carries the full burden but only states 'Update a linked file'. It does not disclose that the 'confirm' parameter is required for execution, that 'dry_run' exists, or any implications of the update (e.g., overwriting existing fields). This is a severe gap 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero wasted words, which is concise. However, it is under-specified to the point of almost being a tautology; it reads as a restatement of the tool name rather than a useful elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 7 parameters, no output schema, and no annotations, yet the description provides no context about update behavior, required confirmation, dry-run functionality, or return values. It is completely inadequate for an agent to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14% (only 'confirm' has a description). The description adds no meaning to the 7 parameters, failing to explain what 'name', 'url', 'type', 'description', or 'linked_file_id' represent or how they relate to the update operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'linked file', making the tool's purpose immediately obvious. It distinguishes from sibling tools like create/delete/list by its action, but lacks specificity about what aspects of the linked file can be updated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., create_linked_file for new files, delete_linked_file for removal). The description offers no context, prerequisites, or scenarios where updating is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations and no mention of side effects, confirmations, or the dry_run parameter, the description fails to disclose that this is a mutating operation requiring CONFIRM_WRITE to execute. It provides no behavioral context beyond the vague 'create' verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence and is front-loaded, but it is under-specified for a tool with 7 parameters. It omits necessary operational details, so while it is not verbose, it is not appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and lacks any mention of return values, required confirmations, or parameter requirements. Given the 7-parameter schema and no output schema, the description is far from complete for reliable tool invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 7 parameters with only 14% description coverage, and the description adds no explanation of parameters like name, state, confirm, or dry_run. The description does not compensate for the low schema coverage, leaving parameter meaning entirely to the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Create') and resource ('a new milestone in Shortcut'), making the tool's purpose unambiguous. It distinguishes itself from sibling update and list milestone tools by explicitly indicating creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 update_milestone or list_milestones, nor does it mention any prerequisites or context. It simply states the action without any usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
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 only says 'update fields' and fails to mention the required confirm parameter (CONFIRM_WRITE), archive behavior, dry_run support, or any irreversible effects. This is a serious transparency gap 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no wasted words, but for a tool with 10 parameters and important confirmation/archive semantics, it is severely under-specified. This is not appropriate conciseness; it is a gap in essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex (10 parameters, mutation with confirm and dry_run, no annotations, no output schema), yet the description provides only the most basic purpose. It fails to convey the confirmation workflow, safety mechanisms, or field semantics, making it wholly inadequate for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 10% (just the confirm parameter), and the tool description provides no explanation of the 10 parameters. It does not mention fields like name, state, archived, categories, or completed_at_override, so the agent has little guidance beyond raw parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update fields on an existing Shortcut milestone' clearly identifies the action (update), the resource (Shortcut milestone), and distinguishes it from create/delete/get sibling tools. It is specific and unambiguous about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'existing Shortcut milestone' implies the tool is for modifying an already-created milestone, but it offers no explicit guidance on when to prefer this over create_milestone, delete_milestone, or update_epic. Usage context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It only states 'Create', but fails to mention the required confirm parameter (CONFIRM_WRITE) for execution, potential side effects, or success/error behavior. This is a significant gap 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no fluff, but it is under-specified for a tool with 15 parameters. While it earns its place, it could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 15 parameters, no annotations, and no output schema, yet the description is just one short sentence. It omits usage guidelines, parameter semantics, and behavioral expectations, making it severely incomplete for such a complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, and the description adds no parameter information at all. It does not explain the required name and project_id fields or any optional fields, failing to compensate for the large portion of undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with the resource 'Shortcut story in a project', clearly defining the tool's function. It distinguishes from siblings like update_story and create_epic by focusing on creation of a story entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as update_story or create_story_task. There is no mention of prerequisites or scenarios where other tools would be more appropriate, leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits, but it does not mention that this is a write operation, the confirm parameter, or the dry_run option. It also incorrectly suggests 'is blocked by' as a valid verb, potentially misleading agents. This falls short of expected transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is underspecified. It lacks any structured breakdown of behavior or parameters. It is short but not optimally informative, making it only minimally acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no annotations, and no output schema, this description is incomplete. It omits information about confirm and dry_run, does not explain the direction of the link, and fails to describe return values or error behavior, leaving significant gaps for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already documents 80% of parameters, the description adds little value. It does not clarify the directional semantics of subject_id and object_id beyond what the schema says, and the 'is blocked by' example is inconsistent with the verb enum, potentially causing incorrect parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: linking two stories together with example relationship types. It is distinguishable from siblings like delete_story_link and create_story. However, it lists 'is blocked by' as an example although the schema enum does not include it, which slightly muddles the precise set of allowed verbs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as delete_story_link or update_story. It does not mention any specific scenarios, prerequisites, or exclusions, leaving the agent without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only states the basic action and resource, without revealing pagination, permissions, return format, or the purpose of the dry_run parameter. This adds minimal behavioral insight beyond the tool name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler, efficiently conveying the core purpose. It is not overlong, though its terseness limits the detail it provides.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description covers the primary action but omits usage context, parameter semantics, and behavioral details. With no annotations or output schema, the description leaves notable gaps in understanding what the tool returns and how to invoke it appropriately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not elaborate on either parameter. While story_id is inferable from the tool name, the dry_run parameter is entirely unexplained, leaving the agent without semantic information to correctly populate the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'List' and clearly identifies the resource as 'external links attached to a Shortcut story.' It is specific and unambiguous, but it does not explicitly differentiate itself from sibling tools like list_linked_files or list_story_tasks beyond the resource name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of context, exclusions, or sibling tools, leaving the agent without decision criteria for when to select this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must fully disclose behavioral traits. It only states 'update fields' without mentioning that the mutation is potentially destructive, that a 'confirm' parameter is required for execution, or that a 'dry_run' option exists. This is a significant transparency gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that is immediately readable and front-loaded. There is no unnecessary information, but it omits important contextual richness that could be added without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with 9 parameters, no annotations, and no output schema. The description is far too minimal to guide an agent effectively; it does not explain the confirm/dry_run behavior, the write semantics, or the return value. The tool needs substantially more context to be used correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 11%, yet the description names no parameters or field categories. It adds no meaning beyond the schema, failing to compensate for the low coverage. For example, it does not mention that fields like name, color, archived, or abbreviation are updatable.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update fields on an existing Shortcut project' clearly identifies the action (update) and the resource (project), distinguishing it from sibling tools like update_epic. However, it lacks any specification of which fields can be updated, making it slightly less precise than ideal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as create_project or delete_project. There is no mention of prerequisites, context, or exclusions, leaving the agent without information about appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It says only 'Create a new iteration,' omitting the CONFIRM_WRITE requirement, the dry_run safety mechanism, and any side effects or permission needs. The agent receives no warning that this mutation requires explicit confirmation, which is a critical behavioral gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It conveys the core purpose efficiently, though it is minimal and could be slightly more informative without hurting conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This tool has 9 parameters, no annotations, no output schema, and a safety confirmation requirement. A one-sentence description is grossly insufficient for an agent to invoke it correctly. It fails to mention required fields, the confirmation flow, or how creation interacts with other iteration tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no meaning for any of the nine parameters. Schema description coverage is only 33%, and the description fails to compensate for the undocumented parameters like confirm, dry_run, group_ids, label_ids, and follower_ids. Even common parameters like name are left entirely to the agent's inference.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Create a new iteration (sprint) in Shortcut.' This clearly distinguishes it from sibling tools like update_iteration, delete_iteration, get_iteration, and list_iterations by its create action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 create_iteration versus update_iteration or other iteration tools, no prerequisites such as the need for start_date and end_date, and no mention of alternatives. It only states the bare action without any decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only restates the listing operation and does not explain the dry_run parameter's effect, pagination, return format, or other behavioral traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is appropriately concise for a simple listing tool, though it sacrifices useful detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity but still includes an unexplained dry_run parameter and no output schema. The description omits any mention of this parameter and any usage context relative to sibling tools, making it insufficient for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter dry_run has zero schema description coverage, and the description does not mention it at all. The agent cannot determine what dry_run does or how it affects the listing, making this a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('List') and resource ('epics') in the Shortcut workspace, making its core operation unambiguous. It does not explicitly distinguish from sibling tools like search_epics or get_epic, but the listing scope is clear enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use list_epics versus search_epics, get_epic, or list_epic_stories. The description only states what the tool does, leaving the agent to infer selection 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It only says 'list' without explaining return format, sorting, limits, or the purpose of the dry_run parameter. It does not contradict annotations (none exist), but it is very thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, which is easy to parse, but it is so short that it borders on underspecification. It earns no extra credit for being front-loaded because it contains so little information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description leaves critical gaps: no mention of output format, no explanation of dry_run, and no usage guidance. Since there is no output schema, the description should at least hint at what a milestone entry looks like, but it does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, dry_run, is a boolean with no description in the schema. The tool description does not mention it at all, leaving the agent without any clue what dry_run does. With 0% schema coverage, the description fails to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb and resource: "List milestones in your Shortcut workspace." It unambiguously identifies this as a list operation for milestones, distinguishing it from sibling list tools like list_epics or list_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives (e.g., get_milestone, list_milestone_epics), nor does it mention any filtering, pagination, or prerequisite context. It is bare of usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 does not state that this is a read-only operation, nor does it explain what 'query syntax' entails, how results are returned, or any potential side effects. This leaves safety and expectations unclear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, making it concise and front-loaded. However, it lacks structure such as examples or parameter hints, though it remains appropriately sized for the minimal information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no annotations, and incomplete parameter documentation, the description is insufficient. It does not explain return values, pagination, or the behavior of dry_run, making it incomplete for a search tool that likely needs clarification on these aspects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema documents only the 'query' parameter (33% coverage), and the dry_run and page_size parameters are unannotated. The description adds no extra meaning about these parameters, especially the non-obvious dry_run flag, leaving their semantics unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (search) and resource (Shortcut epics), and the phrase 'query syntax' hints at a search interface. It is distinguishable from sibling list_epics which likely lists all epics without a query, though it does not explicitly contrast with search_stories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool over alternatives like search_stories or list_epics. It does not mention any prerequisites, context, or situations where this tool is preferred, leaving the agent without direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It only mentions 'Shortcut query syntax' and does not describe return format, pagination, rate limits, or explicitly confirm it is a read-only operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words, front-loading the verb and resource. It is concise, though the brevity contributes to under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three parameters and no output schema, the description is insufficiently informative. It lacks details on query syntax, return structure, and parameter behavior, making it inadequate for a correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, with only 'query' described. The description does not explain 'dry_run' or 'page_size', leaving the agent without necessary context for these parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Search' and identifies the resource as 'Shortcut stories', making the tool's purpose clear. However, it does not explicitly differentiate from sibling tools like search_epics, so it falls short of 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.
Usage Guidelines2/5
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 such as search_epics. There are no exclusions, prerequisites, or context about appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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. Solely stating 'Update fields' omits critical traits such as the require_confirm field needing 'CONFIRM_WRITE', the dry_run option, and archiving behavior. No destructive or safety-relevant details are exposed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no unnecessary words. It is front-loaded and easily scannable, though this conciseness comes at the cost of behavioral depth.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex mutation tool with 12 parameters, no annotations, and no output schema, yet the description is only a bare statement of purpose. It lacks mention of return values, confirmation workflows, partial update semantics, or field interdependencies. Extremely inadequate for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 8% (only the confirm parameter has a description), and the description adds no parameter-specific meaning. Saying 'fields' is redundant with the schema. The tool's 12 parameters remain largely undocumented in prose, and the description fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb 'update' and resource 'existing Shortcut story', making the core purpose understandable. However, it doesn't differentiate from sibling tools like transition_story_state or archive_story, which also modify stories, so it's not a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as transition_story_state, archive_story, or bulk_update_stories. Prerequisites (e.g., story must exist) and exclusions are absent, 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.
Behavior2/5
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 only states 'create' without mentioning the required confirm parameter, dry_run option, or any side effects. The description is minimally transparent and does not reveal important safety or execution details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or repetition. However, it is extremely terse for a tool with 8 parameters, so while concise, it sacrifices informative content for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of an 8-parameter create operation, no annotations, and no output schema, a one-line description is not enough. The agent is left without context about required inputs, confirmation behavior, or expected outcomes, making the description incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 8 parameters but only 13% have descriptions, and the tool description adds no parameter-level meaning. Required fields like name, the confirm flag, dry_run, and group_id are left entirely unexplained, so the agent cannot correctly populate them based on this description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new epic in Shortcut' uses a specific verb ('Create') and resource ('epic'), clearly distinguishing it from sibling tools like update_epic or archive_epic. It is concise and unambiguous about the tool's primary function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as update_epic or create_milestone. No context is provided about prerequisites, exclusions, or typical use cases, leaving the agent to infer usage solely from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits, but it only says 'Create a comment.' It omits critical details such as the confirm parameter requirement, dry_run option, potential side effects, or reversibility. This is a significant transparency gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no wasted words. It is efficiently structured, though extremely brief, which is appropriate for the simple action described but leaves out necessary context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given five parameters, no output schema, and no annotations, the description is insufficiently complete. It does not mention the confirmation workflow, dry-run capability, or optional author_id, leaving users without enough context to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only confirm is described). The description adds no parameter-level detail beyond 'comment' and 'story.' It does not explain author_id, confirm, dry_run, or the relationship between story_id and text, failing to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states 'Create a comment on a Shortcut story,' using a specific verb and resource. It clearly distinguishes from sibling tools like update_story_comment and delete_story_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, when to prefer this over update_story_comment or list_story_comments, or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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. The description only states 'List iterations' without revealing return format, pagination, or the existence of a dry_run parameter. It does not disclose any behavioral traits beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff or redundant wording, making it highly concise. However, while it is well-structured, it is so brief that it omits critical information, which slightly detracts from its effectiveness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description is incomplete: it fails to mention the dry_run parameter and any behavioral aspects like result set or filtering. Given the lack of annotations and output schema, the description should provide more context but does not, leaving the agent uncertain about how the tool behaves.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one property 'dry_run' with no description (0% schema description coverage), and the tool description does not mention or explain this parameter. Since the description does not compensate for the missing schema documentation, the parameter semantics are completely opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'iterations (sprints)' within the 'Shortcut workspace', which specifically differentiates it from sibling tools like list_projects or list_members. It uses a specific verb+resource pattern that leaves no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as get_iteration or get_iteration_stories. The description implies usage for listing all iterations, but it does not provide explicit context, exclusions, or mention of alternatives, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 disclosing behavior. It only says 'List projects' without explicitly stating that this is a read-only, non-destructive operation, nor does it mention what the return value looks like. The presence of a dry_run parameter further complicates expectations, as the description does not explain its effect. This leaves the agent guessing about side effects or simulation behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that is front-loaded with the action and resource. It is concise and avoids unnecessary words, though it is slightly under-specified. It earns its place but could have included more useful detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple but lacks essential context. There is no output schema, no annotations, and the one parameter (dry_run) is unexplained. The description does not clarify return format or behavior beyond the basic listing action. Given the missing details, the description is not complete enough for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema contains one parameter (dry_run) with no description, and the description does not mention it at all. With 0% schema description coverage, the description was expected to compensate, but it provides zero information about dry_run's meaning or usage. The parameter name alone might hint at a dry-run mode, but this is insufficient, especially for a list operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List projects in your Shortcut workspace' uses a specific verb ('List') and resource ('projects'), clearly distinguishing it from sibling tools like list_members or list_labels. It states exactly what the tool does without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 does not mention any exclusions, prerequisites, or sibling tools such as get_project for retrieving a single project. Usage is only implied by the tool name and title, not explicitly explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 does not mention the required 'confirm' parameter (CONFIRM_WRITE) or the 'dry_run' option, which are critical for understanding how the tool actually executes mutations. It also omits details about permissions, idempotency, or side effects, leaving significant ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, but it is overly generic ('fields') and omits essential context. While brevity is a virtue, the sentence sacrifices informativeness for simplicity, making it less effective than a slightly longer version that names the key updatable attributes.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 10 parameters, no annotations, and no output schema, this one-sentence description is severely incomplete. It fails to explain the required confirmation token, the dry-run workflow, which fields can be updated, or what the tool returns, leaving an agent without adequate information for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 10% (only 'confirm' has a description). The description merely says 'Update fields' without listing any specific fields or explaining the meaning of parameters like group_ids, label_ids, follower_ids, or date formats. It adds no meaning beyond the raw schema property names, and thus fails to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Update') and resource ('Shortcut iteration'), clearly stating that it modifies an existing entity. This distinguishes it from sibling tools like create_iteration, get_iteration, and delete_iteration, which handle creation, retrieval, and deletion respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for updating an existing iteration, but provides no explicit guidance on when to use this tool versus alternatives or any prerequisites/exclusions. The context makes it the obvious choice for modifying iterations, yet it lacks explicit 'when to use' or 'when not to use' guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for behavioral transparency. It only states the action 'move' without disclosing the confirmation requirement (confirm parameter), dry-run support, or any side effects or permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, making it efficient. However, the brevity contributes to lack of detail, but conciseness itself is well-handled.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with a confirmation guard and dry-run option, the description is inadequate. It doesn't mention required confirm, the dry_run parameter, or the epic_id option, and there's no output schema to compensate. Agents would be under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 83% (5 of 6 params have descriptions). The description adds minimal value by mentioning project and workflow state, but doesn't explain confirm or dry_run semantics, which are critical for safe execution.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves multiple stories to a different project and/or workflow state, which is a specific batch operation. However, it omits the ability to move to an epic (epic_id parameter), making the purpose slightly incomplete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 compared to siblings like bulk_update_stories or transition_story_state. It just states the action without context or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, but it only says 'Add a checklist task' without revealing important behavioral details. It does not disclose the write confirmation requirement (confirm='CONFIRM_WRITE'), the dry_run option, or whether the action is reversible. This leaves the agent unaware of safety mechanisms visible in the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler or repetition. It is front-loaded and easy to scan, though it is sparse enough that some behavioral and parameter information is missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has six parameters, no annotations, and no output schema, the one-sentence description is inadequate. It does not mention the confirmation/dry-run workflow, the meaning of optional fields, or what the tool returns after creating a task, leaving significant gaps for an agent to operate correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, and the description does not compensate. It implicitly conveys that story_id identifies the target story and description is the task text, but it omits semantics for owner_ids, complete, confirm, and dry_run, which are not described in the schema either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Add') and resource ('checklist task to a Shortcut story'). It unambiguously distinguishes this from siblings like create_story, update_story_task, and delete_story_task.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions or direct the user to update_story_task or delete_story_task for modifications or removals, leaving usage to be inferred entirely from the name and one-line description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden of behavioral disclosure. It does not mention that the operation is read-only, describe the return format, or note any side effects or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence that is clear and without waste. However, it is under-specified, missing details that an agent would benefit from, so it does not reach the highest level.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an undocumented dry_run parameter and no output schema, yet the description provides no explanation of dry_run's purpose, the response structure, or any contextual cues. This is incomplete for safe and correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'numeric iteration ID' for iteration_id, but that duplicates the schema's integer type. The dry_run parameter is entirely unexplained, leaving a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a specific Shortcut iteration by its numeric ID. The verb 'Get' and resource 'Shortcut iteration' are precise, and the ID-based lookup differentiates it from list-type siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives like get_iteration_stories or list_iterations. No exclusions, prerequisites, or comparison to siblings are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'Get the change history' but does not disclose return format, ordering, pagination, or the effect of the dry_run parameter. There is no contradiction with annotations (none exist), but the behavioral context is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no wasted words. It is appropriately sized for a simple tool, though it could be longer without becoming padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and two parameters including an unexplained dry_run, the description is far from complete. It needs to explain what the history contains, how dry_run behaves, and the expected response shape.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining story_id and dry_run. It doesn't mention any parameters, leaving dry_run's purpose completely unexplained. This is a critical gap for the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' with a clear resource 'change history of a Shortcut story', effectively distinguishing it from sibling tools like get_story (current state) and list_story_tasks. It precisely states the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives. It doesn't mention typical scenarios, exclusions, or how it relates to get_story or other story history-related tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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. The verb 'List' implies a read-only operation, but the description does not explicitly state that it has no side effects, nor does it explain the dry_run parameter, which is a notable behavioral aspect. This omission leaves uncertainty about what the tool actually does when invoked.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler or redundant phrasing. It immediately states the tool's action and target, making it easy to scan and parse. This is appropriately concise for a simple list operation, with every word contributing to clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and an output schema, the description should provide more context, especially around the dry_run parameter and expected return value. It only states the basic purpose, leaving the agent with unanswered questions about behavior and response format. The tool is simple, but the missing parameter explanation makes the description incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter (dry_run) with no description, and schema description coverage is 0%. The description does not mention or explain this parameter at all, leaving the agent without any semantic clue about its purpose or valid values. The description completely fails to compensate for the lack of schema-level documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List all labels in your Shortcut workspace' clearly specifies the action (List), the resource (labels), and the scope (Shortcut workspace). This distinguishes it from sibling list_* tools like list_projects or list_members, which target different resources. The purpose is unambiguous and directly useful for tool selection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 merely restates the function without mentioning contexts, exclusions, or comparisons to sibling tools such as list_custom_fields or list_iterations. There is no explicit 'use this when' direction, leaving the agent to infer usage solely from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits, but it only states 'list all' without indicating read-only status, pagination, or any side effects. The presence of a dry_run parameter is unexplained, introducing uncertainty about whether the operation could have side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundant words. It is front-loaded with the action and resource, making it appropriately concise for a simple list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is simple, the description is incomplete: it fails to explain linked files, the purpose of dry_run, or any filtering/pagination behavior. The lack of an output schema does not excuse the missing parameter context, and the description provides minimal assistance for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter 'dry_run' has no schema description (0% coverage), and the description does not explain its meaning or behavior. The description adds no value beyond the schema's bare type declaration, leaving the agent completely uninformed about how to use the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'list' with resource 'linked files' and scope 'all in your Shortcut workspace', making it clear what resource is being acted on. It is easily distinguishable from sibling list tools that target other resources like projects, members, or milestones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as get_linked_file for a single file or create_linked_file for adding a linked file. The description does not mention any prerequisites or exclusions, leaving the agent with no direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only says 'Update fields on an existing Shortcut epic,' with no mention of side effects, confirmation requirement, dry-run capability, or permission needs. The schema includes a confirm parameter, but the description adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one clear, front-loaded sentence with no wasted words. However, it is under-specified for the tool's complexity, so it loses a point for appropriate sizing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 10 parameters, no annotations, and no output schema, this description is severely incomplete. It lacks essential context about confirmation, dry run, archiving, and required fields, making it inadequate for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description uses the generic term 'fields' and names none of the 10 parameters. With schema description coverage of only 10%, the description fails to compensate by explaining critical parameters like epic_id, confirm, dry_run, or state.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates fields on an existing Shortcut epic, using a specific verb and resource. It distinguishes from siblings like create_epic, get_epic, and delete_epic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The verb 'update' implies use for modifying existing epics, but there is no explicit guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only states that the tool updates text; it does not disclose side effects, permission requirements, overwrite semantics, or the role of confirm and dry_run parameters. This is a mutation tool with no safety signals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundancy. It is front-loaded with the action and object, making it very concise and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and a schema with required confirm/dry_run semantics, the description is severely incomplete. It fails to mention that confirm must be CONFIRM_WRITE, what dry_run does, or what happens on execution, making safe invocation impossible without external knowledge.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only 'confirm' has a description). The tool description adds no parameter context beyond the word 'text,' leaving story_id, comment_id, dry_run, and confirm semantics mostly unexplained beyond their names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' and identifies the exact resource ('the text of a comment on a Shortcut story'). This clearly distinguishes it from sibling tools like create_story_comment, delete_story_comment, and list_story_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as create_story_comment or delete_story_comment. There is no mention of prerequisites, how to obtain comment_id, or scenarios where updating is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It states the read operation but does not mention pagination, return format, or the effect of the dry_run parameter, which is especially relevant given the schema includes it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler; it communicates the core operation efficiently. However, it omits parameter and usage details, but those are separate concerns.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and two parameters only one of which is obvious, the description is too sparse. It fails to explain dry_run behavior or the shape of the returned story list, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description must compensate. It only loosely implies that iteration_id specifies the iteration, and provides no explanation for dry_run. This is insufficient for an agent to populate parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('stories in a Shortcut iteration'), making the operation clear. It distinguishes from sibling tools like get_iteration (iteration details) and list_iterations (iteration list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool instead of alternatives like search_stories or list_epic_stories. The context of needing all stories for a specific iteration is only implied by the name and description, not stated explicitly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only restates the basic 'Get' action and fails to explain what dry_run does, how missing IDs are handled, or what response format to expect. The presence of the dry_run parameter in the schema is a notable behavioral detail that the description ignores.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that immediately states the action and key parameter. It is concise with no filler or redundant phrasing. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is too sparse for a tool with two parameters and no output schema or annotations. It fails to explain the dry_run parameter, expected return value, error behavior, or how it differs from list_labels. While the core 'get by ID' purpose is clear, the lack of behavioral and output context makes it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds 'numeric' and 'label ID' semantics for label_id, which is helpful. However, it completely omits dry_run, a parameter with no schema description or enum values, leaving the agent without any guidance on its purpose or acceptable values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a Shortcut label by numeric label ID' clearly states the verb (Get) and resource (Shortcut label) and specifies the lookup key (numeric label ID). This distinguishes it from siblings like list_labels, create_label, update_label, and delete_label, which focus on listing or mutating labels.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 does not mention that this is for retrieving a single label by ID as opposed to listing labels, nor does it explain when dry_run might be useful. There is no when-not or alternative tool mention.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Get', implying a read operation, but it does not explain the purpose of the dry_run parameter, potential errors, or return behavior. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words, clearly stating the action and the parameter type. It is perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has two parameters, one of which is unexplained, and no output schema or annotations. The description is too sparse to provide complete context for invocation, particularly regarding the dry_run parameter and what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no property descriptions (0% coverage), so the description must compensate. It only mentions 'numeric ID', which adds minimal value over the schema's integer type, and completely fails to explain the dry_run parameter. This is inadequate for an agent to correctly interpret and use the parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' with the resource 'linked file' and the identifier 'numeric ID', indicating a single-item retrieval. This distinguishes it from sibling tools like list_linked_files (for listing) and create/update/delete linked file operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when the user knows the numeric ID of a linked file, but it does not explicitly mention alternative tools or conditions for using this tool versus others. This is implied rather than explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description is the sole source of behavioral information. It fails to disclose important traits such as the meaning and effect of the dry_run parameter, pagination, or return format, leaving the agent without critical context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that communicates the core function without unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an unexplained parameter and the absence of annotations or an output schema, the description is not sufficiently complete. It lacks details on behavior, response, and the role of dry_run.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema includes a single 'dry_run' boolean parameter with no description, and the tool description does not mention it at all. With 0% schema description coverage, the description must explain the parameter but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and clearly identifies the resource ('teams/groups') and scope ('in your Shortcut workspace'), making its purpose unmistakable and distinct from sibling listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for enumerating teams/groups but provides no explicit guidance on when to choose this over alternatives like get_group or list_members. It offers no exclusions or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing behavior. It only restates the tool's name ('List all workflows') and adds no detail about side effects, read-only nature, pagination, or the unexpected dry_run parameter. This is a significant gap for a tool that has a non-obvious parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no superfluous words. It is front-loaded and immediately states the action and target, earning a maximum score for conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description is too thin. It doesn't explain the dry_run parameter, what the response contains, or any prerequisites. The presence of a dry_run parameter on a list tool is unusual enough that it absolutely needs explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has one parameter (dry_run) with no description, and the tool description doesn't mention it at all. With schema description coverage at 0%, the description needed to compensate but fails completely, leaving the parameter's purpose entirely unknown.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('workflows') and scopes it to 'all workflows in your Shortcut workspace.' This clearly distinguishes it from sibling list_* tools like list_projects or list_members, which target different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need to retrieve all workflows) but provides no explicit guidance on when not to use it or alternatives. It doesn't mention any exclusions or competing tools, so the usage context is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of disclosing behavior. It discloses that both confirm_archive=true and confirm='CONFIRM_WRITE' are required, which is useful safety information. However, it does not explain the side effects of archiving (e.g., reversibility, status changes) or error responses.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. Every word adds value, and it is front-loaded with the primary purpose followed by the key prerequisite.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with no annotations and no output schema. The description is too minimal to be contextually complete: it omits return values, failure modes, dry_run behavior, and any note about whether archiving is reversible. It does not provide enough context for an agent to fully anticipate the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (confirm and confirm_archive have descriptions). The description adds the requirement that both must be set together, which is not explicitly stated in the schema. However, it does not clarify the meaning or purpose of dry_run or epic_id beyond the schema, leaving some parameter semantics incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Archive a Shortcut epic') with a specific verb and resource. It does not explicitly differentiate from sibling tools like archive_story or delete_epic, but the verb 'archive' is distinct enough to convey the purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., delete_epic for permanent removal, update_epic for edits). The confirmation requirement implies a guarded action, but the description does not explain the appropriate context or scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only says 'Get a Shortcut team/group by UUID' and does not mention read-only behavior, error handling (e.g., 404 if not found), authorization requirements, or response format. The verb 'Get' implies read-only, but no additional behavioral context is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler words. Every part ('Get', 'Shortcut team/group', 'by UUID') contributes to the meaning. It is appropriately sized for a simple get-by-ID tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description should explain return behavior and all parameters. It clarifies group_id but does not mention what the response contains or the purpose of dry_run. The overall context is incomplete for an agent to understand the tool's full contract.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to group_id by specifying it as a UUID, which is more informative than the schema's generic 'string' type. However, the dry_run parameter is entirely unmentioned. With 0% schema description coverage, the description only partially compensates for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states exactly what the tool does: 'Get a Shortcut team/group by UUID.' The verb 'Get' is specific, the resource is clearly named, and the lookup method (by UUID) is specified. It is easily distinguished from sibling tools like list_groups (which lists all groups) and get_member (which retrieves a member).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. It does not mention list_groups for listing all groups or any other sibling tool for related operations. The phrase 'by UUID' is a parameter constraint, not a usage recommendation, so the description offers no when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, placing the full burden on the description. However, the description only says 'Get' without disclosing error behavior (e.g., not found), side effects (none), authentication needs, or why the optional dry_run parameter exists. This minimal disclosure is insufficient for a tool operating without annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficiently worded sentence without redundant information. It is appropriately sized for the tool's simplicity, though it misses opportunities to include parameter hints. No wasted words are present, and the key purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters, no annotations, and no output schema, the description is incomplete. It fails to explain the dry_run parameter, which is a significant gap, and provides no context about error handling or return behavior. An agent would likely lack enough information to use this tool confidently in edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must compensate for parameter documentation. It adds a redundant mention that milestone_id is numeric (already in schema as integer) but entirely omits the dry_run parameter. The description provides minimal added meaning beyond the structured schema, leaving dry_run's purpose unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Get a Shortcut milestone by numeric milestone ID' with a specific verb ('Get'), resource ('Shortcut milestone'), and identifier ('numeric milestone ID'). This clearly distinguishes it from sibling tools like list_milestones, create_milestone, and update_milestone, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a single milestone's numeric ID is known, but it does not explicitly state when to use this tool over alternatives (e.g., list_milestones for browsing all milestones). No exclusions or alternative tool references are provided, leaving usage guidance implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must carry the behavioral burden. The verb 'List' implies a non-mutating read operation, but the description does not disclose the effect of the dry_run parameter, pagination behavior, or any authentication/permission requirements, leaving some ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It earns its place by stating the core purpose, though it could have included a brief note about dry_run without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The purpose is clearly stated, but the description is incomplete because it leaves the dry_run parameter entirely unexplained and offers no guidance on return format or when to use this tool versus get_member. Given the tool's simplicity, covering the parameter would have made it complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter, dry_run, with no description, and the tool description does not mention it at all. Since schema description coverage is 0%, the description completely fails to add meaning to the parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly uses the verb 'List' and identifies the resource as 'members' in the Shortcut workspace, making the operation unambiguous. It distinguishes from sibling get_member by listing all members rather than fetching a single one.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to retrieve workspace members, but it provides no explicit when-to-use guidance or comparison with alternatives like get_member. The context is clear but no exclusions or alternative tool references are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only states the core action and does not mention read-only nature, pagination, ordering, authentication, or what exactly is returned. This is minimal and lacks useful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that is front-loaded with the verb and resource. It contains no fluff and earns every word.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description is adequate but lacks important context. It does not explain what commit information will be returned (e.g., hash, message, author), nor does it clarify how this differs from similar tools. With no output schema, more detail about the return format would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no descriptions for its parameters and the description provides zero parameter information. The required story_id is inferable from context, but dry_run is completely unexplained. With 0% schema coverage, the description fails to compensate, leaving the agent without understanding of key parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('Git commits') with clear context ('associated with a Shortcut story'). It distinguishes itself from sibling tools like list_story_branches and list_story_pull_requests by focusing on commits.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need commits for a story) but provides no explicit alternatives or exclusions. Given the large number of sibling list tools, some guidance on when to choose this over others would be valuable, but it is not misleading.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full behavioral burden. It discloses the 'full set' behavior, indicating a replace operation, but fails to mention required confirmation ('confirm' parameter), dry-run behavior, permissions, reversibility, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. Every word contributes to the core message, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutating tool with four parameters, no annotations, and no output schema, this description is incomplete. It omits crucial details about the confirm safety gate, dry-run behavior, and does not explain the destructive nature of replacing the full label set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description adds little beyond what is in the schema. It reinforces 'full list' for label_ids but provides no explanation for epic_id, confirm, or dry_run, leaving half the parameters undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a label') and the target resource ('Shortcut epic'), and specifies the method ('by providing the full set of label IDs'). This distinguishes it from sibling tools like 'add_story_label' and 'update_epic'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: to set the label set on an epic, you provide the full list of label IDs. However, it does not explicitly state when to use this tool versus alternatives like 'update_epic' or 'add_story_label', nor does it provide any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full behavioral burden but only states the action. It does not disclose side effects, confirmation requirements (e.g., the 'confirm' parameter), auth needs, or return behavior. This is a significant gap for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler. It is front-loaded and every word contributes meaning, making it highly concise and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a nearly complete absence of context beyond the basic action. The description omits the confirmation gate, the optional author_id, dry-run behavior, and any description of the return value (no output schema exists). The agent cannot safely invoke this tool without further information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only 'confirm' has a description). The tool description adds no parameter details: it does not clarify the role of 'text', 'epic_id', 'author_id', or 'dry_run'. While the name implies epic_id and text, other parameters remain undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Create') and identifies the resource ('comment on a Shortcut epic'), making it unambiguous. It clearly distinguishes from sibling tools like create_story_comment, which targets stories, and list_epic_comments, which is for reading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the resource name but the description offers no explicit when-to-use or alternative guidance. It does not state, for example, to use this tool when commenting on an epic versus create_story_comment for stories, nor does it mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only states the read operation and gives no information about error handling, authentication requirements, or the meaning of the dry_run parameter. It fails to disclose what happens for non-existent IDs or the response shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence, front-loaded with the verb and object, and no unnecessary words. It is as concise as possible while still stating the tool's core function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has only two parameters, but one (dry_run) is completely undocumented in both the schema and description. There is no output schema, so the description should explain return values or side effects. The current description leaves critical gaps for a non-trivial boolean parameter.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds some value by specifying that story_id is numeric, but it completely omits the dry_run parameter. The description does not provide enough detail for an agent to understand all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and identifies the resource ('Shortcut story') with a precise lookup method ('by numeric story ID'). It clearly distinguishes from sibling tools that list, search, or update stories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: you need a numeric story ID to fetch a single story. However, there is no explicit guidance about when to prefer this over search_stories or list-based tools, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must state behavioral traits. It only says 'List,' suggesting a read operation, but does not confirm safety, return format, or any side effects. This is minimal and leaves the agent guessing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, zero fluff, front-loaded with the action. It is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema and annotations. The description does not mention the return shape, pagination, or dry_run semantics, making it incomplete for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%. The description adds context for story_id via 'Shortcut story' but does not explain the dry_run parameter at all. The schema only provides names/types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and names the resource 'Git branches' with a clear context 'associated with a Shortcut story.' It is distinct from sibling tools like list_story_commits and list_story_pull_requests.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need branches for a story but provides no explicit alternatives or exclusions. Sibling tools like list_story_commits exist but no comparison is made.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full burden of behavioral disclosure. It only states the list action without revealing any behavioral details such as ordering, pagination, whether completed tasks are included, or any side effects. The presence of a dry_run parameter suggests additional behavior, but the description does not address it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that immediately front-loads the tool's purpose. It contains no filler or redundant information, making it appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple parameter set and lack of annotations and output schema, the description is incomplete. It does not explain the purpose of dry_run, nor does it mention what the return value looks like (e.g., list of task objects). The tool has enough complexity that a bit more context would be beneficial.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description gives indirect meaning to story_id via 'on a Shortcut story', but it does not explain the dry_run parameter at all. Since schema description coverage is 0%, the description should compensate, but it fails to clarify the key boolean parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List checklist tasks on a Shortcut story.' It uses a specific verb ('List') and a specific resource ('checklist tasks on a Shortcut story'). This distinguishes it from sibling tools like list_story_comments or list_story_external_links.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is used to retrieve checklist tasks for a story, but it offers no explicit guidance on when to use it over alternatives or any exclusions. For example, it does not mention that it should not be used for story comments or other related data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry full transparency. It indicates mutation ('Move') but does not disclose the CONFIRM_WRITE requirement, dry-run support, or any state transition constraints. This leaves the agent without critical safety and behavioral context for a write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded verb, no filler. Appropriate size for the minimal content it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters, no annotations, and no output schema, the description is too sparse. It omits the confirmation and dry-run behavior, the role of workflow_name, and the expected response or errors, making the tool under-specified for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is only 17%, so the description needs to compensate. It adds that the target state can be identified by ID or name, which clarifies workflow_state_id and workflow_state_name. However, it does not explain workflow_name, confirm, or dry_run, and no exclusivity or combination rules are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific action ('Move'), identifies the resource ('a story'), and specifies the target ('a new workflow state') with input alternatives ('state ID or state name'). This clearly distinguishes it from siblings like bulk_move_stories or update_story.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for changing a story's workflow state but gives no explicit 'when to use' context or alternatives. It does not mention bulk operations, prerequisites, or cases where update_story should be used instead, so guidance is limited to the obvious interpretation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears the full burden of disclosing behaviors. It does not mention the required 'confirm' parameter (CONFIRM_WRITE), the availability of 'dry_run', potential overwriting of fields, or any irreversible side effects. The description only states it updates a task, leaving the agent uninformed about safety mechanisms and mutation specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence: 'Update a checklist task on a Shortcut story (e.g. mark complete).' It contains no filler words, immediately conveys the action and resource, and the example adds useful context without bloating the text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with 7 parameters, no output schema, and no annotations. The description is minimal and does not cover return values, prerequisite conditions, the meaning of confirm/dry_run, or how fields like owner_ids and description interact. For a tool of this complexity, the description is under-specified and leaves critical gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 14% (1 of 7 parameters has a description). The description adds value for the 'complete' parameter via the example 'mark complete', but it does not explain owner_ids, description, dry_run, or confirm beyond what the schema already states. Given the low schema coverage, the description must compensate more but falls short.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Update') and resource ('checklist task on a Shortcut story'), with a concrete example ('mark complete'). This directly distinguishes it from sibling tools like create_story_task, delete_story_task, and update_story, so there is no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a checklist task on a story needs modification, but it does not explicitly mention alternatives or exclusions. For example, it doesn't say 'use create_story_task to add a task' or 'use delete_story_task to remove one.' The guideline is clear but only implied, not explicitly contrasted with siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral transparency, yet it only states the creation action. It fails to disclose the required CONFIRM_WRITE confirmation, dry-run behavior, or potential side effects, leaving key behavioral traits undocumented in the description itself.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded with the action and resource, then reinforced with two concrete examples. It is concise, scannable, and free of filler or restatement of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 7 parameters, no annotations, and no output schema, a one-sentence description is not complete enough to guide an agent. Important behavioral details like the CONFIRM_WRITE gate, dry_run semantics, and the optional story association are left out, making the description insufficient for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The examples 'Google Doc, Figma link' add meaningful context to the url and type parameters, mapping abstract enum values to concrete services. However, the description does not clarify dry_run, description, or confirm beyond what the schema already states, and 43% of parameters lack schema descriptions or descriptive compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Create' and identifies the exact resource: 'linked file reference in Shortcut'. Including examples like Google Doc and Figma clarifies the domain and clearly distinguishes this from sibling tools such as list_linked_files, get_linked_file, update_linked_file, and delete_linked_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for creating external file references and gives context through examples, but it does not explicitly state when to use this tool over alternatives or mention prerequisites such as the CONFIRM_WRITE requirement. There is no exclusion or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of behavioral disclosure. It does not mention the read-only nature, error handling, response format, or what happens if the epic is not found. Only the basic operation is stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It efficiently communicates the core purpose and the key parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is not fully complete for invoking the tool correctly. The dry_run parameter is unexplained, and with no output schema, there is no information about the return value. An agent would not know the effect of dry_run or what to expect in the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description states 'numeric epic ID', which adds meaning to the epic_id parameter. However, it completely ignores the dry_run boolean parameter, leaving its purpose undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a Shortcut epic by its numeric ID, using a specific verb and resource. This distinguishes it from list/search variants like list_epics and search_epics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have an epic ID, but it provides no explicit guidance on when to use this instead of list_epics or search_epics. No alternatives or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only says 'List comments' without disclosing whether the operation is read-only, paginated, or requires specific permissions. The presence of a 'dry_run' parameter in the schema is not mentioned, introducing ambiguity about the tool's actual behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that conveys the core purpose without fluff. It is appropriately sized for a simple list operation, though it could include more detail without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters (one required) and no output schema, the description fails to explain return values, pagination, or the meaning of 'dry_run'. It is too minimal to fully inform an agent about the tool's behavior and edge cases.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameters. It does not mention 'epic_id' or 'dry_run'. The parameter names are somewhat self-explanatory (epic_id is likely the epic's ID), but 'dry_run' is unclear for a listing operation and the description provides no guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and a clear resource 'comments on a Shortcut epic', which precisely identifies the tool's function and distinguishes it from siblings like list_story_comments (comments on stories) and list_epic_stories (stories in an epic).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description is concise but clearly states the context: listing comments on an epic. This implicitly tells the agent when to use it versus related tools, though it does not explicitly name alternatives or exclusions. The resource (epic) is clear enough for correct selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states a read operation ('List all'), but fails to disclose the dry_run parameter's effect on behavior, or any additional behavioral traits like pagination or return format. The dry_run parameter is a notable omission.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, front-loaded with the action and resource. No filler or redundant text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While this is a simple list tool, the description does not explain the dry_run parameter, and there is no output schema or annotations to fill the gap. The description is adequate for the core purpose but incomplete for a fully informed invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not mention the dry_run parameter at all. The description adds no meaning beyond the bare schema, leaving the parameter's purpose entirely unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all linked Git repositories in the Shortcut workspace. It uses a specific verb (list) and resource (repositories), which distinguishes it from sibling tools like list_projects or list_milestones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the usage context: retrieving linked Git repositories. It differentiates from siblings by specifying 'linked Git repositories', but does not explicitly mention alternatives or when not to use it. Clear context with no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 'List' which implies a read operation, but it does not mention pagination, ordering, authentication, or any side effects. This is minimal behavioral context, similar to the 'update_drive' example.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. It contains no filler and is 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.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description gives the core functionality, but it lacks explanation of the dry_run parameter and provides no usage context. There is no output schema, and the description does not describe the return format, though 'comments' is implied. It is minimally viable but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only clarifies that story_id refers to a Shortcut story. The dry_run parameter is completely unexplained. Since the schema provides no descriptions, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List comments for a Shortcut story' clearly identifies the action (list), the resource (comments), and the scope (for a Shortcut story). This distinguishes it from sibling tools like list_epic_comments or list_story_tasks, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool (when you need comments for a story), but it provides no explicit guidance, exclusions, or alternatives. It does not mention when not to use it or how it differs from similar tools like list_epic_comments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose mutation behavior, but it only says 'update' without mentioning confirmation requirements (like the confirm parameter), partial failures, irreversibility, or side effects. The CONFIRM_WRITE requirement is hidden in the schema, not surfaced here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence, front-loaded with the primary purpose and zero redundancy. It is appropriately sized for a tool with this level of scope, though other dimensions carry the needed detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex 16-parameter mutation tool with no output schema and no annotations. The description provides only a high-level purpose and omits essential operational details like the confirmation workflow, dry-run behavior, effect on existing fields, and error handling, making it incomplete for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 44%, and the description does not enumerate any of the updatable fields beyond saying 'the fields to change on all of them.' It adds no detail about the nine undocumented parameters, so it fails to compensate for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (update), the resource (stories), and the scope (multiple at once), distinguishing it from single-story updates and other bulk operations like bulk_move_stories or bulk_delete_stories.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly indicates when to use this tool: when multiple stories need the same field changes. However, it does not explicitly mention alternatives such as update_story for a single story or exclusions for unsupported fields, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only states 'Get a Shortcut member by UUID' and adds no context about authentication, error handling, return format, or side effects. The read-only nature is implied by 'Get' but not explicitly disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the essential purpose without any fluff or redundancy. It is highly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no output schema and no annotations, the description should explain what is returned or any special behavior. It does not mention the return value at all, and the dry_run parameter remains unexplained. The low complexity helps, but the gaps make it incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must clarify parameters. It helps identify member_id as a UUID, but it does not explain the dry_run parameter at all. With two parameters and no schema descriptions, this leaves a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action ('Get') and resource ('Shortcut member'), and specifies the lookup method ('by UUID'), which distinguishes it from list_members and other getters. It is a specific and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is used when you have a UUID and need a single member. It does not explicitly mention alternatives like list_members, but the context is clear for a simple getter, and no misleading guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden. It only states the core function; it does not disclose the role of the dry_run parameter, the return format, pagination, or error behavior. This lack of behavioral detail leaves the agent guessing about unexpected behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently states the tool's purpose and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description is incomplete for a tool with a dry_run parameter and a specific milestone scope. It fails to explain what dry_run does, what the response contains, or any limitations, making it insufficient for confident invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It only implies milestone_id through 'belonging to a Shortcut milestone' but provides no explanation of dry_run or how milestone_id is used. The description adds minimal meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'List' and clearly identifies the resource 'epics belonging to a Shortcut milestone'. This distinguishes it from sibling tools like list_epics (all epics) and list_milestones (listing milestones).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'belonging to a Shortcut milestone' provides clear context for when to use this tool: when you need epics scoped to a particular milestone. It does not explicitly name alternatives or exclusions, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description correctly carries the burden of disclosing the tool's destructive nature: it states 'Permanently delete' and 'IRREVERSIBLE,' and specifies the required confirmation flags to execute. However, it omits any mention of the dry_run parameter, which could allow safe testing, and does not describe cascading effects on associated data. The key risk of irreversibility is disclosed, so a score of 4 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core action and uses formatting (caps) to highlight irreversibility and required confirmations. Every sentence contributes essential information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a destructive tool with no annotations and no output schema, the description covers the essential facts (permanent deletion, irreversible, required confirmations). However, it omits the dry_run parameter, which is highly relevant for safely testing a destructive operation, and does not mention what happens to associated stories or whether the operation can be undone. This is a clear gap in an otherwise adequate description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes confirm and confirm_delete with the exact requirements that the description repeats, so the description adds no new meaning. It does not explain iteration_id format or the purpose of dry_run, which is undocumented in the schema. With schema coverage at 50%, the description fails to compensate for the missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Permanently delete') and the resource ('a Shortcut iteration'), which differentiates it from sibling tools like update_iteration, get_iteration, and delete_epic. The word 'permanently' adds specificity about the operation's effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as archiving an iteration or using update_iteration. It mentions required confirmations but not when deletion is appropriate or what conditions must be met. There is no explicit when-to-use or when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It explicitly warns 'IRREVERSIBLE' and specifies the required confirmation flags (confirm_delete=true and confirm='CONFIRM_WRITE'), which is essential for a destructive operation. It could add more context about side effects (e.g., what happens to the story) but covers the primary risk well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two sentences (or three clauses) that front-load the purpose and then state critical safety requirements. Every word earns its place, with no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive deletion tool with no annotations and low schema coverage, the description provides essential safety information (irreversibility, confirmation) but leaves gaps. The 'dry_run' parameter is unexplained, and there is no mention of what the tool returns or how errors are handled. It is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (40%), so the description should compensate. It only references the confirmation parameters, which the schema already describes. It fails to explain the remaining parameters, particularly 'dry_run', which is not obvious. The description adds little value beyond what the schema already communicates.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Delete a checklist task from a Shortcut story.' This uses a specific verb and resource, distinguishing it from siblings like delete_story, delete_story_comment, and delete_story_link. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 does not mention other tools like update_story_task or delete_story, nor does it specify situations where this tool should or should not be used. The only instructions are about required confirmation parameters, which are more about execution than usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries the burden of behavioral disclosure. It conveys a read-only listing action, but it does not mention the dry_run parameter or any side effects, return format, or access requirements. The verb 'list' gives a basic safety signal, but more context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that succinctly states the action and resource. Every word is useful, and there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description captures the core purpose, but it omits any explanation of the dry_run parameter and the return structure. Given no annotations and no output schema, the description should provide more information to make the tool fully self-contained. It is minimally adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema defines a single boolean parameter, dry_run, with no description (0% schema coverage). The tool description does not explain this parameter at all, so an agent cannot determine the effect or valid values of dry_run. This is a significant gap that the description fails to compensate for.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all story/epic templates in the Shortcut workspace, using a specific verb and resource. It distinguishes itself from sibling tools like list_projects or list_epics, which focus on different resource types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when a user needs to retrieve all story/epic templates. Although no explicit alternatives or exclusions are mentioned, the tool's unique resource among siblings makes the appropriate context clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 only says 'List all stories', which implies a read operation and scope, but does not address dry_run behavior, pagination, ordering, or any API-side effects or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is concise, direct, and front-loaded with the key action and resource. No filler or redundant wording is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity of the tool, the description is mostly adequate, but the unexplained dry_run flag and lack of return-format or pagination details create meaningful gaps. It is a minimum-viable description for an otherwise simple list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that epic_id identifies a Shortcut epic, but it does not explain the dry_run parameter at all, leaving one of the two schema properties semantically incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and a clear resource ('all stories belonging to a Shortcut epic'), which fully states the tool's function. This differentiates it from sibling tools like list_epics or list_epic_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the use case: retrieving all stories for a given epic. It does not explicitly mention alternatives or exclusions, but the context is unambiguous enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses that this operation sets the full label set, implying it replaces existing labels. However, it does not mention the confirm requirement or the dry_run parameter, which are behaviorally important. With no annotations provided, the description carries additional burden but only partially fulfills it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that directly communicates the action and key constraint. It is appropriately concise with no redundant wording.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and 4 parameters, the description is too minimal. It omits the confirm/dry_run workflow, return behavior, and when to use this tool vs. siblings, leaving the agent without essential safety and selection context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds little beyond the schema: 'full set of label IDs' is nearly identical to the schema's description for label_ids. It does not clarify story_id, confirm, or dry_run semantics. Given only 50% schema coverage, the description fails to compensate for undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a label to a Shortcut story') and the key requirement ('by providing the full set of label IDs'), distinguishing it from sibling tools like remove_story_label or add_epic_label by explicitly targeting stories and specifying the full-set behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'by providing the full set of label IDs' gives clear guidance on how to invoke the tool correctly: the caller must supply all labels, not just one. It provides clear context for the tool's behavior, though it does not explicitly mention when to use this over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It reveals that confirmation parameters are required for execution, which is useful. However, it does not explain what archiving does (e.g., effect on story visibility, reversibility) or the behavior of dry_run.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and states key requirements. Every word earns its place, with no unnecessary filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description is somewhat thin. It covers the core action and confirmation but omits details about the archive's effects, return behavior, and the purpose of dry_run. It is adequate for a simple operation but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%. The description repeats and combines the requirements for confirm_archive and confirm, clarifying that both must be set, but adds no meaning for story_id or dry_run. It provides minimal added value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Archive') and resource ('Shortcut story'), clearly distinguishing it from siblings like delete_story and archive_epic. It unambiguously identifies the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for archiving stories but does not provide explicit when-to-use guidance or mention alternatives. It includes confirmation requirements, which are execution details, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
It discloses irreversibility and required confirmation parameters, adding safety context beyond the schema. However, it omits the dry_run parameter's behavior, which could make the absolute statement 'permanently delete' misleading. With no annotations, the description should clarify this, but it doesn't.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose and critical safety information. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers core intent and required confirmations, but it fails to mention dry_run behavior, which is part of the schema. This is a notable gap for a delete operation, leaving ambiguity about whether the tool always deletes or can simulate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies that both confirm and confirm_delete are required (schema only marks story_id required) and states their expected values, adding meaning beyond the schema. However, it does not address dry_run, and schema description coverage is only 50%, so not all parameters are compensated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'delete' and resource 'Shortcut story' with clear scope 'by ID'. It distinguishes itself from sibling deletion tools like delete_epic or delete_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description warns that deletion is IRREVERSIBLE, implying it should only be used when permanent removal is intended. However, it does not explicitly mention alternatives like archive_story or bulk_delete_stories, so guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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 explicitly states 'Permanently delete' and 'IRREVERSIBLE,' and it discloses the required confirmation flags, which is strong transparency for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences with essential information front-loaded. Every word earns its place, and the capital 'IRREVERSIBLE' draws attention to the key risk without adding fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the description covers critical safety concerns, it omits the behavior of dry_run and does not mention permissions or what happens on success/failure. Given the lack of annotations and output schema, more context would be helpful for a destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 40%, so the description needs to compensate. It adds exact expected values for confirm and confirm_delete, but it does not clarify the dry_run parameter, which is semantically ambiguous, and it leaves story_id and comment_id to be inferred from names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('delete') with a clear resource ('comment on a Shortcut story') and further specifies it is permanent. It clearly distinguishes this tool from siblings like update_story_comment or delete_story.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as update_story_comment or delete_story. It includes required confirmation values, which are operational prerequisites rather than usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the confirmation requirement ('Requires confirm='CONFIRM_WRITE'') and the unusual semantics of label_ids ('Provide the remaining label IDs after removal'), which are important behavioral details. However, it does not mention the effect of dry_run, what happens if the label does not exist, or potential side effects beyond the removal. Since no annotations are present, the description carries the full burden, and it only partially meets it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, each serving a distinct purpose: stating the action, clarifying the parameter semantics, and noting the confirmation requirement. It is front-loaded with the primary function and avoids redundancy or extraneous detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 provides the essential purpose and the key parameter constraint, but it omits details about dry_run behavior and the outcome of an empty label_ids array. The tool is relatively simple, yet the description leaves some ambiguity about the full set of behaviors, making it adequately complete but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides descriptions for label_ids and confirm, covering 50% of parameters. The description repeats and reinforces these, particularly the meaning of label_ids as the remaining labels, which is critical. However, story_id and dry_run lack descriptions in both the schema and the description, leaving a coverage gap. The description adds some value but does not fully compensate for the missing parameter information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Remove a label from a Shortcut story.' This is a specific verb and resource, and it distinguishes the tool from siblings like add_story_label, which performs the opposite operation. The purpose is explicit and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives such as update_story or add_story_label. It does mention the requirement for confirm='CONFIRM_WRITE', which provides guidance on invocation but not on selection among similar tools. The usage context is implied rather than directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. 'Get' implies a read-only operation, but the description doesn't disclose potential errors (e.g., 404), return format, or any side effects. This is minimal but not misleading.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is front-loaded and contains no filler. Every word contributes to the purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get operation with two parameters and no output schema, the description covers the core function adequately. However, the unexplained dry_run parameter and lack of return value details prevent it from being fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions 'numeric project ID' for project_id, which adds no information beyond the schema's integer type. The dry_run parameter is completely unaddressed, leaving a gap for a required optional parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get'), the resource ('a Shortcut project'), and the identifier ('by numeric project ID'). This distinguishes it from sibling tools like list_projects, create_project, and delete_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when you have a specific numeric project ID and need that project's details. It provides clear context for when to use this tool, though it doesn't explicitly mention alternatives like list_projects for retrieving multiple projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It implies a read-only operation via 'List' and provides useful context that it returns all fields and their possible values. However, it does not explicitly state side-effect-free behavior, authentication needs, or other behavioral constraints, leaving some transparency gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff. It front-loads the action and resource, and every phrase adds value (e.g., 'all', 'possible values', 'in your Shortcut workspace'). Perfectly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool, the description adequately communicates the main function and output. However, it leaves the 'dry_run' parameter unexplained and does not describe the return format beyond 'possible values'. Given no output schema and no annotations, there is room for more completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema includes one parameter 'dry_run' with no description (0% coverage). The tool description does not mention 'dry_run' at all, so the agent receives no additional meaning about this parameter. Since schema coverage is low, the description should have compensated, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'custom fields', and adds 'their possible values' which specifies the output. It distinguishes this tool from other list_* siblings by focusing on custom fields with a concrete example ('Priority').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool: when you need to list all custom fields in the workspace. It doesn't explicitly mention alternatives, but no alternative exists among siblings for custom fields. There are no exclusions or when-not-to-use instructions, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'List' conveys a read-only operation, but it does not disclose any additional behaviors, such as whether closed PRs are included or how the dry_run parameter affects execution. This is adequate but has gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the action and resource. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with only two parameters and no output schema, the description is minimally viable. However, the purpose of dry_run remains ambiguous, and there is no mention of return format or edge cases, so it leaves some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It mentions a 'Shortcut story' which implies story_id, but the dry_run parameter is completely unexplained. The description adds minimal semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List'), the resource ('pull requests'), and the scope ('associated with a Shortcut story'). This distinguishes it from sibling tools like list_story_commits or list_story_branches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool: when you need pull requests for a specific Shortcut story. It provides clear context but does not explicitly mention alternatives or exclusions, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explicitly discloses irreversibility and the dual confirmation requirement, which is critical behavioral information. It does not mention what happens to associated data (e.g., stories, comments) or the response format, but for a delete tool this is a solid disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. The critical information (irreversibility, required confirmations) is front-loaded and immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with no output schema and four parameters, the description covers the key aspects: what it deletes, the required confirmations, and irreversibility. It lacks explicit guidance on alternatives (archive_epic) and effects on related resources, but remains largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50%. The description adds meaning to confirm and confirm_delete by specifying required values ('CONFIRM_WRITE' and true), and it indirectly defines epic_id via 'by ID'. However, dry_run is not mentioned at all, leaving a gap in the undocumented parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Permanently delete'), the resource ('a Shortcut epic'), and the mechanism ('by ID'). It also distinguishes from the sibling archive_epic by emphasizing irreversibility, making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for permanent deletion but does not explicitly state when to use this tool versus archive_epic (which is reversible). Since archive_epic is a sibling tool, providing an explicit alternative would strengthen this dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the burden of disclosing behavioral traits. It explicitly states 'IRREVERSIBLE' and 'Permanently delete,' clearly indicating destructive behavior. It also specifies confirmation requirements, which are important for safe execution. It does not mention permissions or additional side effects, but the key behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: two short sentences that front-load the core purpose ('Permanently delete a linked file'), then add critical safety and usage details. Every word earns its place with no unnecessary fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given this is a destructive tool with no annotations and no output schema, the description covers the crucial aspects: permanence and the need for explicit confirmation. However, it completely omits any explanation of the dry_run parameter, which is particularly relevant for a destructive operation and is not described in the schema. This is a notable gap for an otherwise concise description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats the confirmation parameter requirements that are already documented in the schema (confirm must be 'CONFIRM_WRITE' and confirm_delete must be true), adding no new meaning. It does not provide any guidance for linked_file_id or dry_run, and the schema coverage is only 50%, leaving two parameters completely undocumented. Thus, the description fails to compensate for the schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Permanently delete a linked file.' It uses a specific verb+resource and emphasizes irreversibility, which distinguishes it from sibling tools like update_linked_file or create_linked_file. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for use: it is for permanently deleting a linked file and explicitly requires confirm_delete=true and confirm='CONFIRM_WRITE' before execution. It does not explicitly mention when not to use it or name alternatives, but it gives enough usage context to guide the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the transparency burden. It clearly discloses that deletion is IRREVERSIBLE and requires explicit confirmation, which are important behavioral traits. It does not mention potential cascading effects or return values, but the irreversibility warning is significant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that front-loads the action and immediately follows with the most important requirements. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential delete action and confirmation requirements, but omits the dry_run parameter behavior and any post-deletion effects or return value. Since there is no output schema, the description could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description repeats the confirmation requirements already documented in the schema (confirm and confirm_delete), adding no new meaning. It does not address the dry_run or milestone_id parameters, which have no schema descriptions. With 50% coverage, the description should compensate for the undocumented parameters, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool permanently deletes a Shortcut milestone, using a specific verb and resource. It distinguishes itself from sibling tools like create_milestone, update_milestone, and list_milestones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly mentions the required parameters confirm_delete=true and confirm='CONFIRM_WRITE', giving clear execution prerequisites. It does not compare with alternatives, but the context is strong enough for correct usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses that deletion is irreversible and requires explicit confirmation, which is critical behavioral information. It does not mention dry_run semantics or error outcomes, but the key safety traits are covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three concise sentences, each adding value: purpose, irreversibility, and confirmation requirements. It is front-loaded and free of redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool, it covers the essential purpose and safety warnings. However, it omits the meaning of dry_run (a parameter with no schema description) and does not describe return values or fallback behavior. The absence of an output schema and annotations increases the burden, making this only minimally adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 50%, and the description fails to compensate. It repeats confirm and confirm_delete requirements already in the schema but provides no explanation for story_link_id or dry_run. This leaves the dry_run parameter completely unexplained, adding little value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a link between two stories' with a specific verb and resource. This distinguishes it from sibling tools like delete_story or delete_epic, which delete different entities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context: use this to delete a story link. It also includes important prerequisites (confirm_delete=true, confirm='CONFIRM_WRITE'). However, it does not explicitly mention alternatives or when not to use the tool, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of disclosing destructive behavior. It explicitly states 'Permanently delete' and 'IRREVERSIBLE', and it discloses the required confirmation flags, which signals a safety mechanism. However, it does not describe side effects on associated data (e.g., stories, epics) or what happens with dry_run, leaving some behavioral aspects undisclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only two sentences, front-loading the core purpose and then adding essential safety information. Every word earns its place, and it is highly scannable for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is adequate for a destructive tool with confirmation requirements, but it omits the semantics of dry_run and does not indicate the expected return value or outcome. Given the lack of an output schema and annotations, the description should fill these gaps to be fully complete. It covers the most critical context (permanence and confirmation) but leaves some operational aspects ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes confirm and confirm_delete, and the description reiterates them without adding new semantic detail. It does not explain project_id or dry_run, which the schema leaves undocumented. Schema coverage is only 50%, and the description does not compensate for the uncovered parameters, so it provides only marginal added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Permanently delete a Shortcut project' with a specific verb and resource. It also highlights irreversibility, which distinguishes it from non-destructive project operations like update_project. As one of several delete_* siblings, the target resource is unambiguous, so it differentiates from delete_story and delete_epic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use when permanently deleting a project. It explicitly states the confirmation requirements (confirm_delete=true and confirm='CONFIRM_WRITE'), which serves as a prerequisite for invocation. However, it does not mention alternative tools or explicit 'when not to use' scenarios, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses the irreversible nature ('IRREVERSIBLE') and the double-confirmation requirement, which are critical safety traits for a destructive operation. It does not cover what happens to dependent data, but the core risk is clearly communicated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence. It states the action first, then the critical caveat and requirements. Every word earns its place, with no fluff or repetition of schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive bulk operation with no annotations or output schema, the description covers the essential aspects: action, scope, irreversibility, and required confirmations. The missing dry_run is a minor gap given the safety emphasis, but the tool remains invocable correctly based on the description alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 75%, not quite the >80% threshold for baseline 3, so the description should compensate for the undocumented parameter. It does explain the semantics of confirm and confirm_delete, and story_ids is self-evident, but it omits any mention of dry_run, which is a meaningful gap for a delete operation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool's function: 'Permanently delete multiple stories at once.' The verb 'delete' and resource 'stories' are specific, and 'multiple' distinguishes it from the sibling tool delete_story, which handles a single story.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context that this tool is for bulk deletion, contrasting with single-delete alternatives. It does not explicitly name alternatives or state when not to use it, but the 'multiple stories' phrasing is sufficient for an agent to select the appropriate tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explicitly warns 'IRREVERSIBLE' and 'Permanently delete', which clearly discloses the destructive behavior. It also specifies mandatory confirmation parameters, which is valuable context beyond what annotations would provide (though annotations are absent). It does not mention side effects on stories using the label, but the core destructive trait is well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three short sentences, each earning its place: purpose, warning, and requirements. It is tightly written, with the critical 'IRREVERSIBLE' warning front-loaded in caps. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation, the description covers the essential aspects: what it does, irreversibility, and required confirmations. The only missing element is an explanation of dry_run, but the tool's overall simplicity and the presence of a confirmation mechanism make this a minor omission. No output schema means return value expectations are not needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description directly specifies the required values for confirm_delete and confirm, aligning with the schema's parameter descriptions. However, it does not explain the dry_run parameter at all, leaving a gap. With schema description coverage at 50%, the description partially compensates for the undefined parameters but not fully.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('delete') and resource ('Shortcut label') with a clear qualifier ('Permanently'), making the tool's function unambiguous. It also distinguishes itself from sibling tools by naming the exact resource type. The first sentence alone fully captures the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context: use this to permanently delete a Shortcut label. It does not explicitly mention alternatives or exclusions, but the resource is specific enough that the intended use is obvious. There is no comparison to create_label or update_label, but the destructive nature is highlighted.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![shortcut-mcp-server MCP server](https://glama.ai/mcp/servers/ptamb3/shortcut-mcp-server/badges/card.svg)](https://glama.ai/mcp/servers/ptamb3/shortcut-mcp-server)

Score Badge

Copy to your README.md:

[![shortcut-mcp-server MCP server](https://glama.ai/mcp/servers/ptamb3/shortcut-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/ptamb3/shortcut-mcp-server)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ptamb3/shortcut-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server