Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Plane MCP list my projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Connect Claude to your Plane workspace to manage projects, work items, cycles, modules, and more — directly from Claude.
The official Plane MCP server is Python-based and supports both cloud and self-hosted Plane instances. It offers OAuth, hosted HTTP endpoints (mcp.plane.so), and Redis-backed sessions. This package is a lightweight Node.js alternative:
Zero infrastructure — runs locally via npx, no Python/Docker/Redis needed
Single dependency — just @modelcontextprotocol/sdk, installs in seconds
Optimized tool count — 77 core tools by default (vs 80+ in the official server) tuned for reliable AI model tool selection, with an opt-in extended mode for full 108-tool coverage
Bulk operations — bulk_create_work_items with automatic rate-limit handling (not in the official server)
Use the official server if you need OAuth or hosted HTTP transport. Use this one if you want a fast, minimal Node.js MCP that works over stdio.
You need a Plane API key. To generate one:
Go to https://<your-plane-host>/<workspace>/settings/account/api-tokens
Click Add personal access token
Copy the token
You also need your workspace slug (the URL path segment for your workspace, e.g. my-workspace).
Related MCP server: plane-mcp-server
Install the package from npm and configure Claude Desktop or Claude Code to use it. The MCP server runs locally on each user's machine — no hosted infrastructure required.
Your machine Cloud
┌─────────────────────────────┐
│ Claude Desktop / Claude Code│
│ ↕ stdio (stdin/stdout) │
│ plane-mcp-server (Node.js) │ ──HTTP──→ Plane Instance
└─────────────────────────────┘ (plane.company.com)Each user runs the server locally via npx. The server receives tool calls from Claude over stdio and calls the Plane REST API directly using the user's API key.
Add to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"plane": {
"command": "npx",
"args": ["-y", "@zethictech/plane-mcp-server"],
"env": {
"PLANE_BASE_URL": "https://your-plane-instance.com",
"PLANE_API_KEY": "YOUR_PLANE_API_KEY",
"DEFAULT_WORKSPACE_SLUG": "your-workspace-slug",
"PLANE_MCP_EXTENDED": "false"
}
}
}
}Set
PLANE_MCP_EXTENDEDto"true"to enable all 108 tools (admin, archives, intake, time tracking, etc.). Leave as"false"or omit for the default 77 core tools.
Restart Claude Desktop after saving.
claude mcp add plane \
--command npx \
--args "@zethictech/plane-mcp-server" \
--env PLANE_BASE_URL=https://your-plane-instance.com \
--env PLANE_API_KEY=YOUR_PLANE_API_KEY \
--env DEFAULT_WORKSPACE_SLUG=your-workspace-slug \
--env PLANE_MCP_EXTENDED=falseAdd
--env PLANE_MCP_EXTENDED=truefor the full 108-tool set.
Variable | Required | Description |
| Yes | Your Plane instance URL |
| Yes | Personal Plane API token |
| Yes | Workspace slug from your Plane URL |
| No | Set to |
By default, the server exposes 77 core tools — optimized for reliable tool selection by AI models. Set PLANE_MCP_EXTENDED=true to enable all 108 tools including admin, archive, and niche features.
Category | Tools |
Projects | list, create, retrieve, update, delete projects; get members |
Work Items | list, search, create, update, delete; retrieve by identifier (e.g. DEV-42) |
States & Labels | list, create, retrieve, update, delete states and labels |
Cycles | list, create, retrieve, update, delete; manage cycle work items; transfer |
Modules | list, create, retrieve, update, delete; manage module work items |
Epics | list, create, retrieve, update, delete epics |
Milestones | list, create, retrieve, update, delete; manage milestone work items |
Initiatives | list, create, retrieve, update, delete initiatives |
Comments | list, create, retrieve, update, delete comments on work items |
Relations & Links | manage work item relations and external links |
Activities | list work item activities (audit log) |
Pages | create, retrieve pages (workspace or project) |
Workspace | get current user, get members |
Bulk Operations |
|
PLANE_MCP_EXTENDED=true)Category | Tools |
Project Admin | get/update project features; project worklog summary |
Workspace Admin | get/update workspace features |
Cycle Archives | archive, unarchive, list archived cycles |
Module Archives | archive, unarchive, list archived modules |
Work Item Types | list, create, retrieve, update, delete work item types |
Work Item Properties | list, create, retrieve, update, delete custom properties |
Intake | list, create, retrieve, update, delete intake work items |
Time Tracking | list, create, update, delete work logs |
Activities (extra) | retrieve individual activity entries |
Server not starting?
Verify all three environment variables are set (PLANE_BASE_URL, PLANE_API_KEY, DEFAULT_WORKSPACE_SLUG)
Check that your Plane instance URL has no trailing slash
Run npx @zethictech/plane-mcp-server --version to verify the package loads
Stale npx cache?
npx --yes @zethictech/plane-mcp-serverAPI errors?
Ensure your API key is valid and has access to the workspace
Check that the workspace slug matches the URL path in your Plane instance
See CONTRIBUTING.md for setup instructions and how to add new tools.
MIT
Add work items to a cycle. Provide an array of work item UUIDs in issue_ids. Get work item IDs from list_work_items and cycle_id from list_cycles.
| Name | Required | Description | Default |
|---|---|---|---|
| cycle_id | Yes | ||
| issue_ids | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint false and destructiveHint false. The description adds that the tool is additive and requires existing work item UUIDs, but it does not disclose side effects such as whether duplicate items are allowed or whether the operation replaces the existing cycle contents. This is adequate but not deeply transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, action-first, with no fluff. The second sentence provides practical sourcing guidance for the required IDs, making every word earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple additive operation with three required parameters, the description offers sufficient context for an agent to select and invoke the tool: it names the action, tells what to provide, and where to get the IDs. It omits project_id explanation and return behavior, but these are minor gaps for this use case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains issue_ids as an array of work item UUIDs and points to list_cycles for cycle_id, but project_id is not mentioned at all. Partial compensation; two of three parameters receive added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add work items to a cycle') with a specific verb and resource. It distinguishes itself from sibling tools like remove_work_item_from_cycle and transfer_cycle_work_items by explicitly framing this as an additive operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides concrete usage context by directing users to get work item IDs from list_work_items and cycle_id from list_cycles. It implicitly shows when to use this tool (when adding existing items) but does not explicitly contrast with removing or transferring items.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add work items to a milestone.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_ids | Yes | ||
| project_id | Yes | ||
| milestone_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond annotations. Annotations indicate readOnlyHint=false (write) and destructiveHint=false (non-destructive), but the description does not explain idempotency (e.g., whether re-adding an existing item duplicates it), side effects (openWorldHint=true suggests possible external effects), or permission requirements. There is no contradiction, but no extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, making it extremely concise and front-loaded. However, it is too minimal to be useful; it provides no structured details, no usage context, and essentially repeats the tool name. While brevity is positive, under-specification reduces the value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (3 parameters, no output schema, sparse annotations), the description is incomplete. It lacks information about behavior, parameter relationships, preconditions, and results. The tool is one of many similar add/remove tools for different containers (cycle, module, milestone), so without more context, the agent may not fully understand how to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the meaning of project_id, milestone_id, or issue_ids. It only mentions 'work items' and 'milestone' conceptually, which maps to issue_ids and milestone_id but does not clarify relationships or constraints. The description fails to compensate for the schema's lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Add work items' and the target 'milestone'. It distinguishes from sibling tools like remove_work_items_from_milestone and add_work_items_to_cycle, though it lacks additional scope or parameter detail. The basic 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.
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, no prerequisites (e.g., milestone must exist), and no mention of related operations like removing work items. It simply states the action without any contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add work items to a module. Provide an array of work item UUIDs in issues. Get work item IDs from list_work_items and module_id from list_modules.
| Name | Required | Description | Default |
|---|---|---|---|
| issues | Yes | ||
| module_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description doesn't need to restate that it's a write operation. However, it adds no additional behavioral context such as idempotency, permission requirements, or what happens if items are already in the module. The description adds no value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the purpose, and provides practical instructions without any filler. Every sentence earns its place and the structure is clear and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should indicate what happens on success or what is returned, but it doesn't. It also fails to explain 'project_id' or any error conditions, making the tool description incomplete for a 3-parameter operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for all parameters. It explains the 'issues' parameter as an array of work item UUIDs and how to get 'module_id', but it omits 'project_id', which is also required. This incomplete parameter guidance is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Add work items to a module' with a specific verb and target resource, distinguishing it from sibling tools like add_work_items_to_cycle or add_work_items_to_milestone. 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit context by telling the agent to get work item IDs from list_work_items and module_id from list_modules, which helps with parameter sourcing. However, it does not mention when not to use this tool or name alternatives, so it lacks explicit exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple work items at once with automatic rate limiting and retry on 429. Pass an array of items — each with the same fields as create_work_item. Returns created IDs and any failures. Use this instead of calling create_work_item in a loop for 10+ items.
| Name | Required | Description | Default |
|---|---|---|---|
| items | Yes | Work items to create | |
| project_id | Yes | UUID of the project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses automatic rate limiting, retry on 429, and the return format including failures, which goes beyond the basic annotations. It does not mention atomicity across items or behavior on partial failures, but the disclosed details are substantial and useful. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each packed with value: the action, the automatic behaviors, and the usage recommendation. No fluff, front-loaded with the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a bulk-creation tool with two parameters and no output schema, this description covers the essential aspects: what it does, how items are structured (via reference to create_work_item), what it returns, and when to prefer it. This is complete for an agent to select and invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the two parameters with 100% coverage. The description adds the crucial context that each item must match create_work_item's fields, which maps the array structure to a known sibling tool and helps agents understand acceptable item shape without repeating the nested schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific action 'Create multiple work items at once', clearly distinguishing this bulk operation from the sibling create_work_item. It also specifies the input structure (array of items) and the return of created IDs/failures, leaving 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Use this instead of calling create_work_item in a loop for 10+ items.' This gives a clear threshold and names the alternative, which is exactly what usage guidelines should do.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new cycle (sprint) in a project. The owned_by field requires a user UUID — get it from get_workspace_members or get_me. Dates should be YYYY-MM-DD format.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| end_date | No | ||
| owned_by | Yes | ||
| timezone | No | ||
| project_id | Yes | ||
| start_date | No | ||
| description | No | ||
| external_id | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnlyHint=false and destructiveHint=false. The description adds operational context beyond annotations, such as the requirement for a user UUID in owned_by and the expected date format. It stops short of describing return values or error behavior, but it provides meaningful additional transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first states purpose, the second delivers crucial parameter guidance. Every clause 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter creation tool with no output schema and zero schema descriptions, the description covers only two fields. It omits the return value (likely the new cycle ID), potential failure modes, and the meaning of optional fields, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description compensates by explaining owned_by as a user UUID and dates as YYYY-MM-DD. However, it leaves 7 other parameters unaddressed; some are self-explanatory by name (project_id, name), but optional fields like timezone, external_id, and external_source lack semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Create a new cycle (sprint) in a project', which uses a specific verb and resource, clearly distinguishing from sibling tools like list_cycles, update_cycle, and delete_cycle. The parenthetical 'sprint' adds helpful synonym context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance on sourcing the required owned_by field from get_workspace_members or get_me, and specifies the YYYY-MM-DD date format. It does not explicitly mention when not to use this tool or alternatives, but the create-vs-modify distinction is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new epic in a project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| point | No | ||
| state | No | ||
| labels | No | ||
| parent | No | ||
| type_id | No | ||
| is_draft | No | ||
| priority | No | ||
| assignees | No | ||
| project_id | Yes | ||
| sort_order | No | ||
| start_date | No | ||
| external_id | No | ||
| target_date | No | ||
| estimate_point | No | ||
| external_source | No | ||
| description_html | No | ||
| description_stripped | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond the annotations. Annotations already indicate the operation is a write (readOnlyHint=false) and non-destructive, but the description doesn't disclose side effects, permission requirements, or expected response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It earns its place for basic purpose but provides no additional detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a creation tool with 18 parameters and no output schema, the description is severely under-specified. It lacks information about required parameters, return values, relationships to existing entities, and any side effects. It is minimally viable at best.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fails to explain any of the 18 parameters. It only mentions 'project' obliquely, which does not help disambiguate fields like point vs estimate_point, description_html vs description_stripped, or the meaning of state and priority. The agent must guess or use external knowledge.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create), resource (epic), and scope (in a project). It is unambiguous and naturally distinguishes itself from sibling tools like create_work_item or create_project by naming the specific resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, no prerequisites (e.g., project must exist), and no mention of exclusions. The agent is left to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new initiative.
| Name | Required | Description | Default |
|---|---|---|---|
| lead | No | ||
| name | Yes | ||
| state | No | ||
| end_date | No | ||
| logo_props | No | ||
| start_date | No | ||
| description_html | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false and destructiveHint=false, but the description adds no behavioral context such as permissions, return value, or validation. It simply restates the creation action without operational details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, but this is under-specification rather than effective conciseness. It does not front-load any important details beyond the basic create operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with seven parameters, no output schema, and no property descriptions, this description is severely incomplete. It fails to provide enough context for an agent to correctly construct a valid create request.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not mention any of the seven parameters. The agent must rely solely on property names, which is insufficient for parameters like 'logo_props' or 'state'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'create' and the resource 'initiative', making it unambiguous. However, it offers no additional scope or differentiating detail 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.
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 other create tools or alternatives. There are no prerequisites, exclusions, or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new label in a project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| color | No | ||
| parent | No | ||
| project_id | Yes | ||
| sort_order | No | ||
| external_id | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description aligns with annotations (readOnlyHint=false, destructiveHint=false) but adds no further behavioral context. It does not disclose side effects, permission requirements, or response behavior. The description contributes no value beyond what annotations already indicate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundancy. It is front-loaded with the primary action and object, 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with seven parameters, no output schema, and zero schema descriptions, the description is severely under-specified. It fails to address parameter meaning, expected behavior, or return values, leaving the agent with insufficient information for correct invocation beyond the schema's raw parameter names.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description should compensate by explaining parameter meanings. However, it only mentions 'project' and 'label' generically, offering no insight into the seven parameters (name, color, parent, project_id, sort_order, external_id, external_source). Required parameters project_id and name are not elaborated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'create' with resource 'label' and scope 'in a project', clearly distinguishing it from sibling tools like list_labels, retrieve_label, update_label, and delete_label. It unambiguously 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.
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 not to use it, or references to update_label/delete_label for modification or removal. The description simply states the action without contextual direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new milestone in a project.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| project_id | Yes | ||
| external_id | No | ||
| target_date | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and non-destructive behavior. The description adds no extra behavioral context such as idempotency, duplicate handling, side effects, or field validation, which could be important for a create operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no unnecessary words, making it easy to read and front-loaded. However, it is extremely brief, which slightly reduces value given the tool's parameter complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With five parameters, a lack of output schema, and no parameter descriptions, the description is incomplete. It does not mention required fields (project_id, title), what the tool returns, or any constraints, leaving the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description does not explain any of the five parameters. It only vaguely hints at a project context, but fails to convey the meaning or requirement of title, target_date, external_id, and external_source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create' with the resource 'milestone' and the context 'in a project', clearly distinguishing this from update/delete/retrieve milestone sibling tools. 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for creating new milestones but does not provide explicit guidance on when to use this tool versus alternatives or any prerequisites. There is no mention of using update_milestone for existing milestones or other context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new module in a project. The lead field requires a user UUID from get_workspace_members. Members is an array of user UUIDs. Dates should be YYYY-MM-DD format.
| Name | Required | Description | Default |
|---|---|---|---|
| lead | No | ||
| name | Yes | ||
| status | No | ||
| members | No | ||
| project_id | Yes | ||
| start_date | No | ||
| description | No | ||
| external_id | No | ||
| target_date | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description is not burdened with those basics. It adds valuable behavioral context: lead must be a user UUID from get_workspace_members, members is an array of UUIDs, and dates follow YYYY-MM-DD format. These details go beyond annotations and help correct invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the main action and followed by essential constraints. No redundant or irrelevant information is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters and no output schema, the description covers the most ambiguous fields (UUIDs and dates) but omits details about status values, external_id/external_source semantics, and return behavior. It is adequate for a simple create operation but leaves some gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 10 parameters with 0% description coverage, so the description must compensate. It explains lead and members as user UUIDs and specifies date format, but it does not clarify external_id, external_source, status, or explicitly state that project_id references an existing project. Parameter names like project_id and name are self-explanatory to some degree, providing partial compensation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new module in a project,' specifying the verb 'create,' the resource 'module,' and the context 'in a project.' This distinguishes it from sibling create tools like create_project and create_work_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides some context by referencing get_workspace_members for the lead field, implying a prerequisite. However, it does not explicitly state when to use this tool versus update/delete/retrieve_module or other alternatives, and no exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new page. If project_id is provided, creates a project page; otherwise creates a workspace page.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| color | No | ||
| access | No | ||
| is_locked | No | ||
| logo_props | No | ||
| project_id | No | ||
| view_props | No | ||
| archived_at | No | ||
| external_id | No | ||
| external_source | No | ||
| description_html | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnly=false and destructive=false, so the description only needs to add extra context. The project_id scoping is useful, but it doesn't disclose return values, permissions, or side effects. This aligns with the get_calls example where annotations cover safety and description adds minimal extra context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence with a front-loaded verb and clear conditional structure. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 11 parameters and no output schema, this description is incomplete. It lacks information on return values, optional parameter behavior, and edge cases. The conditional project_id nuance is helpful but insufficient given the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only explains project_id. The other 10 parameters (name, description_html, color, access, is_locked, etc.) are left entirely unexplained, leaving the agent to guess their meaning and allowed values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new page' and distinguishes between project and workspace pages based on project_id. This specific verb-resource pairing differentiates it from sibling create tools like create_project or create_work_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides conditional guidance on when to use with or without project_id, but does not explicitly mention alternatives or exclusions. The conditional usage is clear but could be more explicit about when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new project.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| emoji | No | ||
| close_in | No | ||
| timezone | No | ||
| page_view | No | ||
| archive_in | No | ||
| cycle_view | No | ||
| identifier | Yes | ||
| cover_image | No | ||
| description | No | ||
| external_id | No | ||
| intake_view | No | ||
| module_view | No | ||
| project_lead | No | ||
| external_source | No | ||
| default_assignee | No | ||
| issue_views_view | No | ||
| is_issue_type_enabled | No | ||
| guest_view_all_features | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what annotations already indicate. It does not mention return values, side effects, permissions, idempotency, or default behaviors. With 19 parameters and no output schema, this lack of additional transparency is a notable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and free of fluff. It states the essential purpose without unnecessary words, making it appropriate concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 19 parameters, no output schema, and no parameter descriptions. The one-sentence description leaves the agent with almost no context about how to invoke the tool correctly, what defaults are applied, or what the result looks like. It is severely incomplete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter explanations. It does not even list required fields or clarify the meaning of parameters like 'emoji', 'close_in', or 'archive_in'. The description completely fails to compensate for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new project.' uses a specific verb and resource, clearly distinguishing this tool from siblings like create_work_item or create_cycle. It unambiguously 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.
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 or any prerequisites. The description gives only the purpose without exclusions, context, or references to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new state in a project. The group field determines where it appears in the workflow: backlog, unstarted, started, completed, or cancelled.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| color | Yes | Hex color code (e.g. "#eb5757"). | |
| group | No | ||
| sequence | No | ||
| is_triage | No | ||
| project_id | Yes | ||
| description | No | ||
| external_id | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive mutation. The description adds context about the 'group' field's effect on workflow placement, which is a behavioral detail. However, it does not disclose other behavioral traits like potential duplicate name validation, required permissions, or what response to expect, which are not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the core purpose and then provides essential detail about the 'group' parameter. Every word earns its place with no redundancy or fluff. This is an optimal length for a create tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters and no output schema, the description is somewhat incomplete. It explains the purpose and the key 'group' field but omits guidance on the other optional parameters which could affect behavior. There is no mention of return value or confirmation behavior, which would be helpful given the absent output schema. Still, the core function is clear enough for basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 11% (only 'color' has a description). The description adds meaning to 'group' by listing valid values, but it does not explain 'sequence', 'is_triage', 'description', 'external_id', or 'external_source'. Even required parameters like 'project_id' and 'name' are not elaborated beyond their obvious names. The description only partially compensates for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with a specific verb and resource: 'Create a new state in a project.' This clearly distinguishes it from other create tools like create_project or create_cycle. It also specifies the key parameter 'group' and its allowed workflow values, which helps the agent understand the tool's role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a new state is needed in a project and explains the 'group' field's effect, but it does not explicitly state when to prefer this tool over alternatives like update_state or delete_state. There is no mention of prerequisites such as the project needing to exist, which would be useful for proper selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new work item (issue) in a project. Requires project_id from list_projects. Use list_states to get state_id, get_workspace_members for assignee UUIDs, and list_labels for label UUIDs. Dates should be YYYY-MM-DD format. Priority is one of: urgent, high, medium, low, none.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| labels | No | ||
| type_id | No | ||
| priority | No | ||
| state_id | No | ||
| assignees | No | ||
| parent_id | No | ||
| project_id | Yes | ||
| sort_order | No | ||
| start_date | No | ||
| external_id | No | ||
| target_date | No | ||
| estimate_point | No | ||
| external_source | No | ||
| description_html | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the create behavior is expected. The description adds contextual behavior: prerequisite parameter requirements, date formatting, and priority enum values. It doesn't contradict annotations, and adds meaningful operational context beyond what annotations provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with purpose, then dependencies, then format notes. Each sentence 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-complexity tool (15 params, no output schema), the description covers the core dependencies and key format constraints. It does not mention what the response includes (e.g., created work item ID), but given the wealth of other guidance, this is a minor omission.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description carries the burden. It explains sources for several critical parameters (project_id, state_id, assignees, labels) and gives valid values for priority and date format. However, it does not explain many optional parameters like type_id, parent_id, sort_order, external_id, or description_html, leaving some gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new work item (issue) in a project' with a specific verb and resource. It distinguishes from sibling tools like update_work_item and delete_work_item by focusing on the creation action, and includes the key target ('work item (issue)').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit dependencies: 'Requires project_id from list_projects', and names specific tools to source other parameters (list_states, get_workspace_members, list_labels). It also gives format and enum constraints for dates and priority, which is actionable guidance for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a comment to a work item.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| external_id | No | ||
| comment_html | Yes | The comment body in HTML format. | |
| work_item_id | Yes | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-destructive operation, but the description adds no further behavioral context such as permissions, side effects, or notification behavior. No additional value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear, front-loaded sentence with no unnecessary words. It is appropriately concise for a simple mutation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no output schema, and low parameter documentation, the description is grossly insufficient. It lacks any information about required inputs, optional integration fields, return behavior, or operational prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20% (only comment_html), and the description does not clarify the meaning of project_id, work_item_id, external_id, or external_source. It 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.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Add a comment to a work item' clearly states the action (add) and the resource (comment on work item), distinguishing it from sibling operations like update_work_item_comment or delete_work_item_comment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as update_work_item_comment or list_work_item_comments. The description only states the basic action without contextual cues or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a link to a work item.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | The URL of the link. | |
| title | No | ||
| project_id | Yes | ||
| external_id | No | ||
| work_item_id | Yes | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnly=false and destructive=false, which aligns with the 'Add' action. However, the description adds no behavioral context beyond the annotations, such as whether this creates an external URL link, how project_id/work_item_id are used, or what response to expect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler, which is structurally concise. However, it is too sparse to be genuinely useful for a tool with six parameters and ambiguous behavior, so it does not fully earn its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With six parameters, no output schema, and minimal annotation help, this one-sentence description is grossly insufficient. It does not cover prerequisites, return values, the meaning of external link fields, or how this tool differs from relation-based tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, with only 'url' described in the schema. The description itself does not explain project_id, work_item_id, external_id, external_source, or title, leaving nearly all parameters semantically opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Add' with resource 'link to a work item', clearly distinguishing it from create_work_item and link-related sibling tools like update_work_item_link. However, it lacks an explicit scope or alternative tool references, so it falls short of a top score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as create_work_item_relation or update_work_item_link. It simply states the action without any context, exclusions, or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a relation between two work items.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| external_id | No | ||
| work_item_id | Yes | ||
| related_issue | Yes | UUID of the related work item. | |
| relation_type | Yes | Type of relation (e.g. "blocked_by", "blocks", "duplicate", "relates_to"). | |
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already convey readOnlyHint=false and destructiveHint=false, so the description adds little beyond a restatement of the create action. It does not disclose side effects (e.g., whether the relation is bidirectional), auth requirements, or open-world implications, providing no additional 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.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that is easy to read and front-loaded with the key action. However, it is so brief that it sacrifices informative content, though this dimension focuses on efficiency and structure, which are solid.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's six parameters, lack of output schema, and the presence of closely related sibling tools (links vs. relations), the description is severely under-specified. It omits return values, side effects, prerequisites, and any distinction between a 'relation' and a 'link', leaving significant gaps for a create operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33%, with four of six parameters lacking descriptions in the schema. The tool description provides no parameter semantics whatsoever, failing to clarify the roles of project_id, work_item_id, external_id, or external_source, nor does it explain how relation_type values like 'blocked_by' or 'relates_to' are used.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create a relation') and the target resource ('two work items'), making the tool's purpose obvious. However, it does not differentiate this tool from sibling tools like create_work_item_link or list_work_item_relations, which also deal with work item relationships.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives such as create_work_item_link or remove_work_item_relation. There is no mention of prerequisites, scenarios, or exclusions, leaving the user to infer appropriate usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a cycle by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| cycle_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds no additional behavioral context such as irreversibility, cascading effects, or permission requirements, offering no value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant wording. It conveys the core action efficiently, though it sacrifices informative detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description lacks essential context for a delete operation: no mention of whether the deletion is permanent, what happens to associated data, what the return response is, or why project_id is needed. Given the lack of an output schema and minimal annotations, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description merely says 'by ID' without explaining the role of project_id or cycle_id, or their formats. The tool requires two parameters, but the description does not help an agent understand how to fill them correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Delete a cycle by ID' which clearly identifies the action (delete) and resource (cycle), distinguishing it from sibling tools like retrieve_cycle and update_cycle. However, it mentions 'by ID' without clarifying which of the two required parameters (project_id, cycle_id) serves as the identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites, and no mention of consequences. The description provides no context about when deletion is appropriate or what conditions must be met.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an epic by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| epic_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, and the description merely confirms the deletion without adding context about scope, irreversibility, or side effects on linked work items. The openWorldHint=true suggests external state changes, but the description does not elaborate on consequences beyond what annotations state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded with the action and resource. However, it is so terse that it sacrifices necessary clarity, though this dimension rewards economy over completeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema, two required parameters, and annotations indicating open-world effects, this description is insufficiently complete. It does not mention what happens after deletion, whether deletion cascades to dependent entities, or any error conditions. The agent would need to rely on implicit knowledge or external documentation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate. The phrase 'by ID' is ambiguous since two required parameters exist (project_id and epic_id). No explanation is given about what each parameter identifies or how they interact (e.g., whether epic_id is globally unique or scoped by project_id).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Delete') and a specific resource ('an epic') with a required identifier ('by ID'). This distinguishes it from sibling delete tools like delete_work_item or delete_project, which act on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of prerequisites, conditions under which an epic should be deleted, or reference to related tools like update_epic for non-destructive changes. The usage context is purely implied by the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an initiative by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| initiative_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete' is redundant. It adds no further context about irreversibility, cascade effects, or failure modes, but it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the action and resource, and contains zero filler or redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple single-parameter delete with annotations covering the destructive nature and no output schema. The minimal description is functionally sufficient for selection, though it could optionally note reversibility or post-deletion effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only adds 'by ID,' which adds no detail beyond the parameter name 'initiative_id' in the schema. It does not specify the ID format, how to obtain it, or any constraints, failing to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Delete' and resource 'initiative' with an identifier parameter, clearly distinguishing it from retrieve/update/list initiatives and sibling delete_* tools. It fully captures the operation's essence in one line.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as updating an initiative or deleting a work item. It does not mention prerequisites, consequences, or contrasts with related CRUD operations, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a label by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| label_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, but the description adds no behavioral context beyond the operation itself. It does not mention irreversibility, project scoping, or potential effects on referenced data, missing an opportunity to enrich the annotation-provided safety signal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no verbose or redundant wording. It is appropriately concise for a delete operation, though it sacrifices useful context for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with no output schema and two opaque parameters, the description is extremely thin. It lacks details about project scoping, irreversibility, or impact on associated work items, which would be expected given the tool's destructive nature and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, and the description does not compensate. It only says 'by ID' but fails to explain the role of project_id or that both IDs are required. The relationship between label_id and project_id is left entirely to the schema parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a label'), which directly distinguishes it from sibling delete_* tools like delete_project or delete_work_item. The phrase 'by ID' aligns with the label_id parameter, 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.
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_label or retrieve_label, nor any context about prerequisites or exclusions. The description simply states the operation without situating it within a workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a milestone by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| milestone_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already provide. Annotations indicate destructiveHint=true and readOnlyHint=false, and the description merely restates the action. It does not disclose consequences such as permanence, cascading effects on work items, or required permissions, which would be valuable beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no redundant wording. It is front-loaded with the action and resource, and every word earned its place. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with destructiveHint and readOnlyHint annotations, the description is minimally adequate. It states the core purpose, but lacks additional details like return value, error handling, idempotency, or prerequisites. Given the low complexity and annotation coverage, a 3 reflects that it is usable but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not compensate. While the parameter names 'project_id' and 'milestone_id' are somewhat self-explanatory, the description does not clarify their relationship (e.g., that a milestone belongs to a project) or where to obtain these IDs. The description thus adds no meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Delete') and resource ('milestone') with a clear scope ('by ID'). This unambiguously communicates the tool's function and distinguishes it from other sibling tools like update_milestone or retrieve_milestone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool, prerequisites, or alternatives. There is no mention of when deletion is appropriate, potential constraints (e.g., deleting a milestone with associated work items), or that one might need to retrieve the milestone first. This lack of usage context leaves the agent to infer when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a module by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| module_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the description adds no extra behavioral context. It does not explain consequences like cascading deletions, reversibility, or required permissions, relying solely on the generic 'Delete' verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, straightforward sentence with no filler words. It is maximally concise while conveying the essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with annotations marking it destructive, this is minimally adequate. However, it omits context such as what happens to associated data or why project_id is required, so it is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema_description_coverage at 0%, the description needed to clarify the roles of module_id and project_id. It only vaguely says 'by ID', which could refer to either parameter. No additional meaning is provided beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a module by ID' uses a specific verb (Delete) and resource (module), clearly distinguishing it from sibling delete_* tools. It also references the role of an ID, making the action unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or conditions. It only states the action, leaving the agent to infer usage from the name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a project by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, but the description adds no context beyond that. It does not disclose that deletion is likely permanent, whether cascading deletion occurs, or any consequences. Since the description carries the burden for any added behavioral context, and it provides none, this is a gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of five words, front-loaded with the key verb and object. There is no fluff or repetition, making it highly efficient for the information it conveys.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description is notably sparse. It omits critical information such as permanence, cascading effects on dependent entities, error behavior when the project does not exist, and any special prerequisites or permissions. The simple schema and annotations do not compensate for this lack of contextual guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has one required string parameter project_id with no description (0% coverage). The description says 'by ID,' which marginally reinforces that project_id is an identifier, but it adds no details about ID format, where to obtain it, or constraints. The parameter name already implies this, so the description adds minimal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a project by ID' clearly states the action (delete), the resource (project), and the identification method (by ID). It distinguishes from sibling delete tools (e.g., delete_work_item, delete_state) by explicitly naming the project resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives, such as update_project or retrieve_project. It does not mention prerequisites, permanence, or any situations where a different tool should be used.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a state by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| state_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare destructiveHint=true and readOnlyHint=false, so the agent knows this is a destructive operation. However, the description adds no additional behavioral context such as permanence, cascading effects, or required permissions, though it does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It conveys the core action and target resource efficiently, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool, the description covers the basic action, but it omits the role of project_id and any mention of side effects or response format. Combined with the lack of an output schema, these gaps leave some ambiguity for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has no parameter descriptions, and the description only says 'by ID', which loosely maps to state_id. The required project_id parameter is completely unexplained, leaving ambiguity about its role and why it is necessary for the deletion.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the resource ('a state') with a specific identifier. It distinguishes itself from sibling delete_* tools by explicitly naming the resource type, 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for deleting states, but it provides no explicit guidance on when to use it versus alternatives or any exclusions. No context is given about prerequisites or situations where deletion should be avoided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a work item by its UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as destructive and not read-only. The description adds no additional behavioral context, such as whether deletion is permanent, cascading, or requires specific permissions. It simply restates the destructive action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no unnecessary words. It front-loads the action and target resource, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simple tool signature and annotations, the description leaves important gaps: it does not explain the role of project_id, nor any side effects or prerequisites beyond 'delete'. The annotations provide safety signals, but the description itself is under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain either parameter. It hints that work_item_id is a UUID, but leaves project_id completely unexplained, failing to compensate for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the target resource (work item) with a unique identifier (UUID). This distinguishes it from sibling tools like create_work_item, retrieve_work_item, and update_work_item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, nor any prerequisites or exclusions. It only implies the purpose of deleting a work item, but there is no explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a comment from a work item.
| Name | Required | Description | Default |
|---|---|---|---|
| comment_id | Yes | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as destructive (destructiveHint=true) and not read-only. The description adds no extra behavioral context: it does not state that deletion is permanent, mention cascading effects (e.g., replies), or note permission requirements. It simply restates the action, adding no value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no filler words. It is front-loaded with the verb and object, making it easy to scan. However, it is concise to the point of being under-specified, sacrificing useful context for brevity, which slightly lowers the score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three required parameters and no output schema, the description should at least note that all three IDs are needed to identify the comment, and perhaps mention that the deletion is scoped to a specific work item and project. It does not, leaving the agent to infer this from sibling tool patterns. The tool is simple, but the description is too thin to be fully self-sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not compensate. It mentions 'a comment' and 'a work item' but does not explain that all three parameters (comment_id, project_id, work_item_id) are required and how they scope the deletion. The parameter names are somewhat self-explanatory, but the description fails to clarify why project_id and work_item_id are necessary or how they relate to the comment.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'delete' and clearly identifies the resource as 'a comment from a work item', which distinguishes it from sibling tools like create_work_item_comment, update_work_item_comment, and list_work_item_comments. 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.
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 that update_work_item_comment is for editing, nor does it note conditions like the comment existing or being owned by the caller. There is no contextual advice whatsoever.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a link from a work item.
| Name | Required | Description | Default |
|---|---|---|---|
| link_id | Yes | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description does not need to repeat the safety profile. However, it adds no extra behavioral context such as irreversibility, whether the linked item is also deleted, or permission requirements. It is not misleading and is consistent with the annotations, meriting a baseline score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the operation. It is front-loaded and every word earns its place. No filler or redundant phrasing is present.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having annotations, the description is too terse for a destructive operation. There is no output schema and no explanation of the difference between links and relations, return values, error handling, or prerequisites. The agent is left without enough context to use the tool confidently in a real workflow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description provides no explanation of the parameters. While the names (project_id, work_item_id, link_id) are self-explanatory, there is no clarification of what a 'link' is, how link_id relates to the work item, or how to obtain these identifiers. The description completely fails to compensate for the lack of schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Delete') and the target resource ('a link from a work item'). It is specific enough to distinguish from sibling tools like create_work_item_link, update_work_item_link, or retrieve_work_item_link, which share the same resource but different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as remove_work_item_relation. The description does not mention prerequisites, typical scenarios, or cases where this tool should not be used, leaving the agent to infer from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the currently authenticated user. Returns the user profile including their UUID, which can be used as an assignee or cycle owner in other tools.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds valuable context that the returned UUID can be reused in other tools, which is not in the annotations, and it does not contradict them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the verb and resource, and every sentence earns its place. There is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema), the description is complete enough. It states what the tool returns and why that result matters, covering purpose and practical context. A more detailed return structure would be nice but is not essential here.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the description correctly avoids parameter details. It adds semantic value by explaining the practical use of the return value (UUID for assignee or cycle owner), which helps the agent understand how to use the output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the currently authenticated user' with a specific verb and resource, and also mentions it returns the user's UUID. This distinguishes it from sibling tools that operate on other resources like projects, work items, or cycles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: when the agent needs the current user's profile, particularly the UUID for use as an assignee or cycle owner in other tools. It does not explicitly name alternatives or when-not-to-use scenarios, but for a single-purpose tool this is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all members of a project.
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds little beyond the annotation, only the scope of 'all members' without mentioning pagination, response structure, or other behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It is appropriately concise for a simple read-only tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
As a simple read-only tool with good annotations, the description covers the core purpose. However, it omits details about pagination/response format and the 'params' parameter, and there is no output schema, so the context is not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has project_id and a generic 'params' object with 0% description coverage. The description implicitly explains project_id (the project whose members are fetched) but says nothing about the 'params' parameter, leaving it unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all members of a project' uses a specific verb 'Get' and a clear resource 'all members of a project'. It distinguishes itself from sibling tools like get_workspace_members (workspace scope) and retrieve_project (project details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for project members, as indicated by 'of a project'. It does not explicitly mention alternatives or when-not-to-use scenarios, but its scope is unambiguous given the sibling list.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Returns the Plane MCP server name and version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states the tool 'returns' information, implying a read-only operation with no side effects. For a simple getter, this adequately conveys the primary behavior, though it omits potential error conditions or response format details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word contributes to clarity, making it optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with no parameters and no output schema. The description tells the agent what the tool returns (server name and version), which is sufficient for basic understanding. It could be slightly more complete by describing the output format, but this is a minor gap for such a trivial endpoint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has zero parameters, so there is no semantic burden on the description. Per the baseline rule for zero-parameter tools, a score of 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool "Returns the Plane MCP server name and version," using a specific verb and resource. This distinguishes it from the extensive sibling list, all of which operate on data entities rather than server metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is given on when to use this tool versus alternatives. However, since it is the only sibling focused on server metadata, the usage context is implied as a utility check. A direct statement about its role as a diagnostic or health-check tool would improve usability.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all workspace members with their user IDs. Call this to find assignee IDs before creating or filtering work items by assignee.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and open-world behavior. The description adds that it returns user IDs, which is useful, but does not disclose additional behavioral details such as pagination, output format, or performance implications. With annotations present, this is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is exactly two sentences: the first states what the tool does, the second provides a practical use case. It is direct, front-loaded, and contains no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only lookup tool, the description fully covers its purpose, output content, and common usage scenario. No output schema exists, but the description sufficiently specifies the key return element (user IDs). It is complete for its intended purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so no parameter explanation is needed. The schema coverage is trivially 100%, and the description's 'all workspace members' clarifies the implied full scope, which is consistent with the empty parameter list.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Get all workspace members with their user IDs.' It distinguishes from sibling tools like get_project_members by specifying 'workspace' scope, making it immediately clear what is returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives explicit usage context: 'Call this to find assignee IDs before creating or filtering work items by assignee.' This clearly indicates when to use the tool, though it does not explicitly mention when not to use it or name alternatives like get_project_members.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all cycles (sprints) in a project. Returns cycle IDs needed for managing cycle work items.
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds context about returning cycle IDs and the project scope, which is useful but does not disclose behaviors like pagination or whether the full cycle objects are returned. With annotations present, the description meets the baseline but adds limited extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the action 'List all cycles...' and no wasted words. Every clause adds value, making it an appropriately sized description for a simple list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list operation with read-only annotations, the description covers the core elements: resource, scope, and the purpose of the output (cycle IDs). The optional params parameter is not explained, and there is no mention of pagination, but given the tool's low complexity and the existing annotations, the description is largely sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It implicitly clarifies project_id as the scope ('in a project') but leaves the optional 'params' object (anyOf object/null) entirely unexplained. With a low-coverage schema, this gap is significant, and the description does not fully clarify parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') with a clear resource ('cycles (sprints)') and scope ('in a project'), directly distinguishing it from sibling tools like list_projects (which lists whole projects) and list_cycle_work_items (which lists work items, not cycles). The added note about returning cycle IDs for managing cycle work items further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'needed for managing cycle work items' implies a use case but does not explicitly say when to use this tool versus alternatives such as retrieve_cycle (for a single cycle) or list_cycle_work_items (for work items within a cycle). No exclusions or alternative references are provided, so the guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all work items in a specific cycle. Requires project_id and cycle_id — call list_cycles first to get the cycle_id.
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| cycle_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds little beyond that, except the dependency on list_cycles for obtaining cycle_id. It does not describe return format, pagination, or other execution behavior, leaving the description to rely on annotations for the read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that front-loads the core purpose ('List all work items in a specific cycle') and then adds the essential prerequisite. Every word earns its place, with no filler or redundant explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with annotations and no output schema, the description covers the essential context: what it does, the required inputs, and the needed prior step. It does not explain the 'params' parameter, but given the tool's simplicity and the presence of annotations, this is a minor gap. The description is complete enough for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining the purpose of project_id and cycle_id, and explicitly tells how to obtain cycle_id via list_cycles. However, the optional 'params' parameter is not mentioned at all, leaving some semantic ambiguity. Overall, it adds meaningful context for the core required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List all work items in a specific cycle.' This specifies the action (list), the resource (work items), and the scope (specific cycle), distinguishing it from the sibling tool list_work_items which likely lists all work items across contexts. The mention of required IDs further clarifies its purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides actionable guidance by stating the required parameters and instructing to 'call list_cycles first to get the cycle_id.' This gives a clear workflow and prerequisite, though it does not explicitly exclude alternatives or state when not to use this tool. The sibling list_work_items is an implied alternative but not named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all epics in a project. Epics are large bodies of work that span multiple work items.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| per_page | No | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and non-destructive. Description adds project scoping and domain definition but does not disclose pagination behavior or return format. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and resource, followed by one clarifying definition. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Simple list tool with good annotations, but pagination params cursor/per_page are not explained in the description. No output schema means return format is unspecified. Description is adequate but leaves gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage and description does not explain cursor/per_page semantics. 'project' implies project_id requirement, but cursor and per_page are left undocumented. Fails to compensate for low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States 'List all epics in a project' with a specific verb and resource. Defines epics to disambiguate from other list_* tools. Clearly distinguishes from list_work_items and list_projects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies use when needing all epics within a given project. Does not explicitly mention alternatives or exclusions, such as retrieve_epic for a single epic or list_work_items for work items. Thus only implied usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all initiatives in the workspace.
| Name | Required | Description | Default |
|---|---|---|---|
| params | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with annotations (readOnlyHint true, destructiveHint false) and adds no contradictions. However, it provides no additional behavioral context beyond what the annotations already declare, such as pagination, data scoping, or response format. The annotations carry the safety burden, so a baseline score is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one concise sentence that clearly states the action and scope without any unnecessary words. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple and annotations confirm a safe read operation, but the lack of parameter documentation and absence of an output schema leave some ambiguity about the optional 'params' argument. The description is minimally adequate for a basic list operation but does not fully address potential usage details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single generic 'params' object with no documented properties and 0% schema description coverage. The description 'List all initiatives' offers no parameter information, leaving the agent with no guidance on optional filters, pagination, or other possible arguments. Since schema coverage is 0%, the description must compensate but fails to do so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'initiatives' with workspace scope, clearly identifying the operation. It distinguishes from sibling tools like create_initiative, retrieve_initiative, update_initiative, and delete_initiative by stating the list action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool vs alternatives such as retrieve_initiative or search_work_items. There is no mention of exclusions, prerequisites, or comparison with other list tools, leaving the agent without explicit usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all labels in a project. Call this to get label UUIDs needed for creating or filtering work items.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| expand | No | ||
| fields | No | ||
| order_by | No | ||
| per_page | No | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the scope 'in a project' and the purpose of returning UUIDs, but it doesn't disclose pagination behavior or the exact structure of the response. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core action and scope. Every word adds value, with no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While annotations cover safety and the description handles the main purpose, the absence of parameter explanations for 6 optional fields leaves the tool under-described. The lack of an output schema increases the burden on the description to clarify response content, which it only vaguely addresses.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 6 parameters. The description only implies project_id via 'in a project' and fails to explain cursor, expand, fields, order_by, or per_page. With such low coverage, the description needed to compensate but did not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all labels in a project, with a specific verb and resource. It also explains the downstream purpose (getting label UUIDs for work items), distinguishing it from sibling tools like 'retrieve_label' or 'create_label'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit guidance on when to call this tool: to get label UUIDs needed for creating or filtering work items. It does not mention alternatives or exclusions, but the use case is clear and contextually grounded.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all milestones in a project. Milestones represent key delivery dates or goals. Returns milestone IDs needed for managing milestone work items.
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not burdened with safety disclosure. It does add context by stating that the tool returns milestone IDs for managing work items, which is useful, but it does not mention pagination, filtering, or the full response structure. This is consistent with the calibration example where annotations cover safety and the description adds modest value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the core action and followed by purposeful context. Every word earns its place; there is no redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with one required parameter, the description covers the main purpose and return-value intent, and the annotations cover safety. However, the unexplained 'params' parameter and lack of output schema mean the response format remains unclear, leaving some gaps. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only indirectly references the project_id parameter ('in a project') without naming it or explaining its type. The optional 'params' object is completely ignored. With no schema documentation, the description needed to compensate but provides only minimal indirect context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'List all milestones in a project,' a specific verb+resource+scope that clearly distinguishes it from sibling tools like list_projects or retrieve_milestone. It also adds purpose-relevant context by noting that milestone IDs are needed for managing milestone work items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use this tool: when you need all milestones for a given project. It even hints at a downstream use case (managing milestone work items), but it does not explicitly mention alternatives such as retrieve_milestone for a single milestone, 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.
List all work items in a milestone.
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| project_id | Yes | ||
| milestone_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description claims 'all work items' while the annotation openWorldHint=true indicates that the result may be incomplete. This is a direct contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, front-loaded with the action, with no unnecessary words. It is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low schema coverage, no output schema, and the openWorldHint annotation, the description is too brief. It fails to clarify the project_id requirement and makes an unqualified promise of completeness ('all') that is contradicted by the annotation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions 'milestone' but does not explain the required project_id or the optional params. The role of project_id is entirely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'list' and identifies the resource as 'work items in a milestone,' which clearly differentiates it from sibling tools like list_cycle_work_items and list_module_work_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives such as list_work_items or list_cycle_work_items. The description only states the action without any contextual usage hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all modules in a project. Modules group related work items by feature or theme. Returns module IDs needed for managing module work items.
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only (readOnlyHint=true) and non-destructive behavior, so the bar is lower. The description adds domain context (modules group work items by feature/theme) and identifies the output value (module IDs), but does not mention pagination, ordering, or filtering behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, no redundancy; front-loaded with the core action and then adds necessary context. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list tool with read-only annotations, the description is mostly adequate, but with no output schema it should be clearer about the return structure (e.g., module objects vs. just IDs) and any list behavior. The purpose and use case are clear, but some operational details remain implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, but it only says 'in a project'; it does not explain the required project_id format or the optional params object. This adds little meaning beyond the schema's property names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('all modules in a project'), and adds context about modules grouping work items by feature/theme. This clearly distinguishes it from retrieve_module and other module management siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The sentence about 'module IDs needed for managing module work items' implies the intended use case: obtaining IDs before managing module work items. It does not explicitly name alternatives or exclusion criteria, but provides clear contextual guidance relative to list_module_work_items/create_module.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all work items in a module.
| Name | Required | Description | Default |
|---|---|---|---|
| params | No | ||
| module_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds a modest behavioral detail by stating it lists 'all' work items in a module, but it does not discuss pagination, ordering, or what fields are returned.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single 6-word sentence with no filler. It is front-loaded and efficiently states the core action, though it is also very terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters and no output schema, yet the description omits any information about return values, pagination, or the relationship between project_id and module_id. It is minimally sufficient for a simple list tool but leaves significant gaps for a client to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only references 'module' (mapping to module_id). It does not explain the required project_id parameter or the optional params object, leaving their meaning and purpose unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb+resource+scope: 'List all work items in a module.' This clearly differentiates from sibling tools like list_work_items, list_cycle_work_items, and list_milestone_work_items by specifying the module context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not explain when to prefer this tool over list_work_items or other list variants, nor does it mention any prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects in the workspace. Call this first whenever you need a project_id to pass to other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| expand | No | ||
| fields | No | ||
| order_by | No | ||
| per_page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safe read nature is covered. The description adds the workspace scope and the 'call first' behavior, but does not disclose pagination, ordering, or response format. It provides some context beyond annotations but lacks richer behavioral detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two concise sentences, front-loaded with the core purpose ('List all projects in the workspace') and followed by a useful usage directive. No redundant or unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with strong annotations, the description covers the primary use case (getting a project_id). However, it omits details about pagination (despite cursor/per_page params) and does not describe the response structure, which would be helpful given there is no output schema. It is adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description offers no explanation for the five parameters (cursor, expand, fields, order_by, per_page). With no parameter descriptions in the schema either, the description fails to compensate, leaving the agent to infer meaning only from parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'List' and resource 'projects in the workspace', clearly distinguishing it from sibling tools like retrieve_project (single project) and create_project/update_project/delete_project (mutations). It unambiguously states 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The instruction 'Call this first whenever you need a project_id to pass to other tools' gives explicit, actionable guidance on when to use this tool. It does not contrast with retrieve_project when an ID is already known, but the directive is clear and contextually strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all states (statuses) in a project. Call this to get state UUIDs needed for creating or filtering work items. States are grouped by: backlog, unstarted, started, completed, cancelled.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| expand | No | ||
| fields | No | ||
| order_by | No | ||
| per_page | No | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that states are grouped by categories (backlog, unstarted, etc.) and that it returns UUIDs for downstream operations. However, it omits behaviors like pagination (despite cursor/per_page parameters) and response structure, which would add more transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and then adds a single clarifying purpose and grouping detail. 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.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and strong annotations, the description is nearly complete: it states what is listed, why it is needed, and the category groups. It lacks details about return format and pagination behavior, and there is no output schema to fill that gap, but the core operational context is well covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% — the description does not explain any of the six parameters. Project_id is implied by 'in a project' but not named. Parameters like cursor, expand, fields, order_by, and per_page are entirely undocumented, and the description does not compensate for this gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource ('List all states (statuses) in a project') and clearly distinguishes this from sibling tools like retrieve_state by emphasizing 'all states'. It also adds the practical purpose of getting state UUIDs for creating or filtering work items, making the tool's role unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use the tool: 'Call this to get state UUIDs needed for creating or filtering work items.' It provides clear context and a concrete use case. It does not explicitly name alternatives or exclusion criteria, but the guidance is strong enough to avoid confusion with single-item retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all activities (history/audit log) for a work item.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| expand | No | ||
| fields | No | ||
| order_by | No | ||
| per_page | No | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds that it returns history/audit log, but does not disclose pagination, filtering, or other behavioral details. It provides some context beyond annotations but not extensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is concise and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is minimal and leaves significant gaps. With no output schema and 7 undocumented parameters, the description does not explain pagination, field selection, ordering, or return behavior. It is barely adequate for basic understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no information about any of the 7 parameters (e.g., cursor, expand, fields, order_by, per_page). The description does not compensate for the missing parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'List all activities (history/audit log) for a work item.' It clearly identifies the tool's function and distinguishes it from siblings like list_work_item_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. There is no mention of exclusions or comparisons with similar tools. The phrase 'for a work item' only implies the required input context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all comments on a work item.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| expand | No | ||
| fields | No | ||
| order_by | No | ||
| per_page | No | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it is safe. The description adds no further behavioral context—no mention of pagination via cursor/per_page, default ordering, or potential large result sets, leaving a gap beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single 7-word sentence is optimally concise; it front-loads the purpose and contains no redundant text. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite read-only annotations, the tool has 7 parameters (including pagination and field selection) and no output schema. The minimal description lacks details on pagination, ordering, and parameter semantics, making it incomplete for full agent guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 7 parameters have no schema descriptions (0% coverage), and the description does not explain or even reference cursor, expand, fields, order_by, or per_page. The description entirely fails to compensate for the absent schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('comments on a work item'), clearly distinguishing it from sister tools like retrieve_work_item_comment (singular) and mutation tools. No ambiguity remains about what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a user needs all comments for a work item, but it does not explicitly offer alternatives or exclusions (e.g., for a single comment, use retrieve_work_item_comment). The context is clear enough, but explicit guidance is absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all links attached to a work item.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| expand | No | ||
| fields | No | ||
| order_by | No | ||
| per_page | No | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the agent knows this is a safe, non-mutating operation. The description adds minimal context by scoping the listing to a specific work item, but does not disclose pagination behavior, potential for partial results due to openWorldHint, or how the 'all' claim reconciles with cursor/per_page parameters. It neither contradicts annotations nor adds substantial behavioral detail beyond them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no filler or redundant content. Every word contributes to the core purpose ('List', 'all links', 'attached to a work item'). It is appropriately front-loaded and minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has seven parameters and no output schema, yet the description only provides a bare summary. It does not explain return value shape, pagination, sorting, field selection, or how 'all' interacts with the cursor/per_page parameters. The one-line description is inadequate for an agent to confidently invoke the tool, especially given the pagination and expansion options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions exist in the schema, and the tool description provides no parameter semantics either. The description does not explain the meaning, purpose, or valid values for cursor, expand, fields, order_by, per_page, project_id, or work_item_id. With seven parameters, the lack of any compensation in the description is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('List') and resource ('all links attached to a work item'), making the tool's purpose immediately clear. It distinguishes itself from siblings like create/update/delete_work_item_link by focusing on listing, and from retrieve_work_item_link by implying multiple links. It also differentiates from list_work_item_relations by explicitly saying 'links' rather than 'relations'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as list_work_item_relations or retrieve_work_item_link. There is no mention of exclusions, prerequisites, or preferred contexts. The only implied usage is from the tool name itself, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all relations for a work item. Relations include: blocked_by, blocks, duplicate, and relates_to.
| Name | Required | Description | Default |
|---|---|---|---|
| cursor | No | ||
| expand | No | ||
| fields | No | ||
| order_by | No | ||
| per_page | No | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, indicating a safe read operation. The description adds the specific relation types returned, which is useful behavioral context. However, it does not mention pagination, expansion, field selection, or any other behavioral details beyond the simple 'list all' scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two short sentences, front-loaded with the main action and followed by a compact list of relation types. Every word adds value; there is no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 7 parameters, no output schema, and a similarly named sibling (list_work_item_links), the description is too thin to provide a complete picture. It leaves pagination, filtering, response details, and the distinction from links unexplained, making the tool harder to use correctly compared to its schema and annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 7 parameters with 0% description coverage, and the description does not explain any of them. Parameters like cursor, expand, fields, order_by, and per_page are left entirely undefined, and even project_id is only implied by context. The description fails to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List all relations for a work item' with a specific verb and resource, and enumerates relation types (blocked_by, blocks, duplicate, relates_to). This clearly distinguishes it from sibling tools like list_work_item_links, which likely handles different link types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives such as list_work_item_links or retrieve_work_item. The main clue is the relation types listed, which imply a use case, but no when-to-use or when-not-to-use information is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List work items (issues) in a project. Supports filtering by priority, state, state_group, assignees, labels, dates, cycle, and module. Use expand=relations,assignees,labels for richer data. Results are paginated — use the cursor from the response to fetch the next page. When linking to a work item, use the format: {PLANE_BASE_URL}/{workspace_slug}/browse/{project_identifier}-{sequence_id}/
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | ||
| cycle | No | ||
| state | No | ||
| cursor | No | ||
| expand | No | ||
| fields | No | ||
| labels | No | ||
| module | No | ||
| archived | No | Include archived work items. | |
| order_by | No | ||
| per_page | No | ||
| priority | No | ||
| assignees | No | ||
| created_by | No | ||
| project_id | Yes | ||
| start_date | No | ||
| subscriber | No | ||
| external_id | No | ||
| state_group | No | ||
| target_date | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds valuable behavioral details beyond annotations: pagination behavior with cursor, the effect of expand on data richness, and the URL format for linking to work items. These are non-obvious traits not captured by the readOnlyHint/openWorldHint annotations, giving the agent a clear understanding of the tool's runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear lead sentence, then filter capabilities, a specific expand usage, pagination instructions, and a linking format example. Every sentence adds operational value without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (21 parameters, no output schema), the description provides essential operational context: filtering options, pagination using cursor, expand guidance, and a materialized URL format. It lacks details on default response structure and error behavior, but is sufficiently complete for a read-only listing tool with good annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at only 5%, the description compensates by listing the key filter categories (priority, state, assignees, labels, dates, cycle, module) and explaining the expand and cursor parameters with concrete examples. However, it omits guidance on many other parameters (order_by, per_page, fields, archived, etc.), leaving some ambiguity for those.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List work items (issues) in a project' with a specific verb and resource, and highlights the project scope, distinguishing it from other list tools like list_cycle_work_items. It also immediately enumerates filtering capabilities, making the tool's purpose immediately comprehensible.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit instructions on using expand, pagination with cursor, and linking format. It explains when to use the tool (listing work items with filters) but does not explicitly contrast it with alternatives like search_work_items or list_cycle_work_items, though the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a work item from a cycle.
| Name | Required | Description | Default |
|---|---|---|---|
| cycle_id | Yes | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false, so the destructive nature is known. The description adds no extra context about side effects, reversibility, or that this only removes the association without deleting the work item. No contradiction with annotations, but no added transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no wasted words, front-loads the core action. It is appropriately sized for its simplicity, though it could afford a bit more detail without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists and the description gives no information about return values, prerequisites, or effects beyond the removal itself. Critical context is missing, such as clarifying that the work item is not deleted, which is especially important given the destructive hint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description provides no explanation of the three required parameters (project_id, cycle_id, work_item_id). The parameter names are somewhat self-explanatory, but the description fails to add any semantic value beyond the bare schema, which is insufficient at this low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Remove' and the specific resource 'a work item from a cycle,' using a distinct verb and resource that differentiates it from sibling tools like add_work_items_to_cycle and transfer_cycle_work_items.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for removing a single work item from a cycle, which is distinct from adding or transferring. However, it does not explicitly state when to use this over alternatives or any exclusions, leaving the guidance somewhat implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a work item from a module.
| Name | Required | Description | Default |
|---|---|---|---|
| module_id | Yes | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is communicated. The description adds no additional behavioral context (e.g., irreversibility, side effects) but does not contradict the annotations. With annotations present, this is an acceptable baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous words. It efficiently states the tool's purpose, making it highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple, and the annotations plus clear parameter names provide a basic understanding. However, the absence of an output schema, parameter descriptions, and usage guidance leaves some gaps, though the operation is straightforward enough for minimal viability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain any parameters. The parameter names (project_id, module_id, work_item_id) are self-explanatory, but the description fails to compensate for the lack of schema documentation, leaving the agent to infer relationships and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove a work item from a module' uses a specific verb and resource, clearly distinguishing it from sibling tools like 'remove_work_item_from_cycle'. It unambiguously states the tool's primary action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as 'add_work_items_to_module' or 'remove_work_item_from_cycle'. There is no mention of exclusions, prerequisites, or recommended use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove a relation between two work items.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| work_item_id | Yes | ||
| related_issue | Yes | UUID of the related work item to unlink. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the destructive nature is known. However, the description adds no context about permanence, side effects, or required authentication. It merely restates the action without disclosing any behavioral traits beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words or filler. It is appropriately sized for the simple operation and front-loads the core purpose effectively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no output schema, the description is too sparse. It does not mention the effect on existing data, whether the operation is reversible, or any result/confirmation. The three required parameters and their roles are not explained beyond the minimal schema hint.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 33% (only related_issue has a description). The tool description 'between two work items' vaguely implies that work_item_id and related_issue are the two work items but does not clarify which is which or what project_id means. This is insufficient compensation for the missing schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove a relation between two work items' clearly specifies the action (remove) and the resource (relation), distinguishing it from sibling tools like create_work_item_relation and list_work_item_relations. The verb is specific and the object is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as create_work_item_relation or list_work_item_relations. There is no mention of prerequisites, applicable relation types, or scenarios where removal is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Remove work items from a milestone.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_ids | Yes | ||
| project_id | Yes | ||
| milestone_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already flag this as destructive (destructiveHint: true) and non-read-only (readOnlyHint: false). The description adds a small but important nuance: work items are only removed from the milestone, not deleted entirely. However, it does not disclose potential side effects like partial failures or whether the operation is idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no filler or redundancy. It communicates the essence of the operation efficiently, scoring high on conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with annotations, the description is adequate but not complete. It lacks context about failure modes, idempotency, or its relationship to the inverse operation add_work_items_to_milestone. It would benefit from noting that it is the reverse of that tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema_description_coverage at 0%, the description does nothing to explain the parameters issue_ids, project_id, and milestone_id. Although the parameter names are somewhat self-explanatory, the description fails to compensate for the lack of schema descriptions, leaving the agent without additional guidance on their format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'remove' and the target 'work items from a milestone', which is specific and distinct from sibling tools like add_work_items_to_milestone or list_milestone_work_items. It immediately communicates 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.
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 remove_work_item_from_cycle or remove_work_item_from_module. The description does not mention any prerequisites, exclusions, or situations where another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a cycle by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| cycle_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and destructiveHint, covering the safety profile. The description adds no additional behavioral context such as response format, error handling, or scoping rules, so it contributes little beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no unnecessary words. It is appropriately concise for a simple retrieval tool, conveying the core action without verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and a minimal description, the tool lacks explanation of the return value (e.g., the cycle object structure) and the role of project_id. The description is too sparse to fully inform an agent about behavior and expected results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has two parameters (project_id, cycle_id) with zero description coverage. The description says 'by ID' but does not explain which ID is which, why project_id is needed, or their relationship. This leaves both parameters semantically unclear.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Retrieve', the resource 'cycle', and the method 'by ID'. It distinguishes this tool from siblings like list_cycles and other retrieve_* tools by specifying the target entity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a single cycle ID is known, but it does not explicitly state when to use this tool versus list_cycles or provide exclusions. No alternatives are mentioned, so guidance is minimal.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve an epic by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| epic_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. However, the description adds no additional behavioral context, such as error behavior, authentication requirements, or response format. It is a minimal read operation, and the description is neither misleading nor informative beyond the name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly conveys the primary action. It is appropriately short for a simple retrieval, though it lacks a bit of helpful detail that would not hurt conciseness, such as mentioning the required identifier context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no output schema and sparse annotations, the description is insufficiently complete. It doesn't indicate what the response contains, what happens if the epic isn't found, or why project_id is necessary. The presence of many siblings and a two-parameter schema demands more context, which is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the parameters have no descriptions in the schema. The description says 'by ID' but only hints at epic_id, while the schema requires both project_id and epic_id. It fails to explain the role of project_id or how the parameters combine, leaving ambiguity about whether both are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve an epic by ID' uses a specific verb ('Retrieve') and resource ('epic'), clearly indicating the action. It distinguishes this tool from sibling tools like list_epics and other retrieve_* tools by naming the exact entity type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool instead of alternatives. It does not mention use cases, exclusions, or reference sibling tools such as list_epics or search_work_items. The agent must 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.
Retrieve an initiative by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| initiative_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds the ID-based retrieval scope, but does not enrich behavioral understanding beyond annotations, leaving out aspects like error handling or response format.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, grammatically complete sentence of five words. There is no redundancy or filler, earning a perfect score for conciseness and structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID operation, the description is functionally adequate: it states the action, target, and how to identify the resource. Yet, with no output schema and no mention of return values or error behavior, it leaves gaps for an agent that might require knowledge of the response structure. The simplicity of the tool partially offsets this but not entirely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides zero description for the only parameter 'initiative_id'. The description's 'by ID' directly ties this parameter to the retrieval action, giving some meaning beyond the bare schema. However, it does not elaborate on format or constraints, barely compensating for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description combines a specific verb 'Retrieve' with the resource 'initiative' and a clear identifier 'by ID', making the tool's purpose immediately clear. It distinguishes itself from sibling tools like 'list_initiatives' (which retrieves multiple) and other retrieve_* tools by specifying the resource type.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: use this when you have an initiative ID and need the full resource. However, it provides no explicit guidance on when to use this instead of alternatives like 'list_initiatives' or when not to use it, leaving the agent to infer the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a label by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| label_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, but the description adds no extra behavioral context such as error cases, authentication needs, or scoping implications. It merely restates the function name without additional details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no fluff, but it is under-specified for a tool with two required parameters and no schema descriptions. It is concise in length but lacks essential detail, so it does not fully earn the conciseness credit.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieve tool with no output schema, the description leaves gaps: it does not indicate what the response will be, why project_id is needed, or any error behavior. Annotations cover safety, but the operational context is incomplete for reliable invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the parameters. It only mentions 'ID' generically, leaving the roles of label_id and project_id ambiguous. The schema parameter names are self-explanatory, but the description adds no value in clarifying their relationship.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve') and the resource ('a label') with the criterion 'by ID'. This distinguishes it from list_labels and other retrieve_* tools, which operate on different resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, exclusions, or that both project_id and label_id are required for the retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a milestone by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| milestone_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context beyond identifying the resource and method.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero waste, directly stating the core function. It is appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is functional but lacks explanation of the dual-parameter requirement and error behavior. With no output schema, it does not fully convey what is returned, though the meaning of 'retrieve' is implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, yet the description only says 'by ID' without clarifying that both project_id and milestone_id are required. This could mislead an agent into thinking only one ID is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve'), the resource ('a milestone'), and the method ('by ID'). This differentiates it from siblings like list_milestones (listing all) and update/delete operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The use case is implied but not explicitly stated. No alternatives or exclusions are mentioned, though the description is straightforward enough for a simple retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a module by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| module_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with annotations (readOnlyHint=true, destructiveHint=false) and implies a safe read operation. However, it adds no additional behavioral context such as whether both project_id and module_id are required, what the response contains, or any side effects. Since annotations cover the safety profile, the minimal description meets the baseline but offers no value beyond the structured data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence and is front-loaded with the primary action. However, it is under-specified, omitting critical information about required parameters and usage. While concise, the lack of necessary content makes it less helpful than it could be, earning a middle score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool requiring two IDs (project_id and module_id) and having no output schema, the description is incomplete. It does not mention the hierarchical relationship between modules and projects, the need to know the project ID, or what is returned. The combination of schema and annotations provides some context, but the description fails to fill the gaps, leaving the agent without enough information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the parameters. It merely says 'by ID,' which is ambiguous given two required parameters (project_id and module_id). It does not clarify that project_id identifies the parent project and module_id identifies the module, nor does it explain why both are needed. This is misleading and fails to convey the actual parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Retrieve') and resource ('module'), clearly indicating the tool fetches a single module. It distinguishes from sibling tools by naming the module resource, though the phrasing is generic ('by ID') and does not explicitly differentiate from other retrieve_* tools 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.
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 versus alternatives like list_modules or other retrieve_* tools. There is no mention of prerequisites, contrast with similar tools, or scenarios where this tool is appropriate or not. The description simply states an action without contextual usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a page by ID. If project_id is provided, retrieves a project page; otherwise retrieves a workspace page.
| Name | Required | Description | Default |
|---|---|---|---|
| page_id | Yes | ||
| project_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey read-only and non-destructive safety. The description adds behavioral nuance by explaining how project_id changes the resource type (project page vs. workspace page), which is valuable beyond the annotations. It doesn't overexplain, but the conditional behavior is a meaningful disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action ('Retrieve a page by ID'), and every word adds value. No redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-parameter retrieval tool with solid annotations, the description covers the essential decision (project vs. workspace page). It does not explain error behavior or return format, but given the tool's simplicity and the absence of an output schema, this is acceptable. It's nearly complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
While the schema has 0% description coverage, the description itself explains both parameters: page_id is the identifier for the page, and project_id is the selector for project vs. workspace page. This adds semantic meaning beyond the schema's type definitions and defaults, though it could be more explicit about the exact values or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb and resource: 'Retrieve a page by ID.' It distinguishes from sibling retrieval tools by targeting 'page' uniquely. The conditional clause about project_id adds scope precision, 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear guidance on when to use this tool for project pages vs. workspace pages: 'If project_id is provided, retrieves a project page; otherwise retrieves a workspace page.' It doesn't explicitly mention alternatives or exclusions, but the conditional context is sufficient for a straightforward retrieval tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a project by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no behavioral context such as return format, error handling, authentication requirements, or what happens when the project does not exist. It merely restates the purpose without going beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence of five words. It is front-loaded with the verb and resource, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieve-by-ID operation with one parameter, read-only annotations, and no output schema, the description is adequate. It communicates the core function, and any missing details (e.g., exact return object) are largely inferable from the tool name and resource context, though it could mention that it returns the full project object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter details. It only says 'by ID', which aligns with the parameter name project_id but does not explain the format, source, or any constraints on the ID. The parameter name is self-explanatory, but the description adds little beyond the schema's type and required flag.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve a project by ID' uses a specific verb (retrieve) and identifies the resource (project) and key (ID). This clearly distinguishes it from sibling tools like create_project, update_project, list_projects, and other retrieve_* tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by the naming convention: use this when you need a single project by its ID. However, it does not explicitly state when to use this over list_projects or mention any prerequisites or alternatives, so the guidance is only implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a state by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| state_id | Yes | ||
| project_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read operation. The description adds no behavioral context beyond 'by ID' (already in the name), but it is consistent with annotations. No extra details about return format or error behavior are provided, but the annotations carry the burden adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It efficiently states the tool's core function, and the brevity is appropriate for a simple retrieval operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the simplicity, the description is incomplete: it fails to explain the required project_id parameter, and without an output schema the agent has no indication of what the response contains. The description relies heavily on the tool's name and sibling context, which is not sufficient for full understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has two parameters with no descriptions (0% coverage), so the description must clarify their roles. It only mentions 'by ID,' which likely refers to state_id, but entirely ignores project_id, leaving the agent unclear about the purpose of the second required parameter and how the two IDs relate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description uses specific verb 'Retrieve' with resource 'state' and scope 'by ID', clearly distinguishing it from sibling retrieve_* tools (e.g., retrieve_project) and from list_states. 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies this tool is for fetching a single state by its identifier, it offers no explicit guidance on when to use it versus list_states or other retrieve tools, nor does it mention any prerequisites. The usage is implied by the name and standard retrieve semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single work item by its UUID. Use expand=relations,assignees,labels for full details. If you have a human-readable identifier like DEV-42, use retrieve_work_item_by_identifier instead.
| Name | Required | Description | Default |
|---|---|---|---|
| expand | No | ||
| fields | No | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this as a safe read-only operation. The description adds useful behavioral context by suggesting expand=relations,assignees,labels, indicating how to get full details. However, it doesn't disclose response format or potential error cases, but the tool's simplicity makes this adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no wasted words. The key information is front-loaded, and each sentence earns its place, including the explicit alternative guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward read-only retrieval tool, the description covers the main usage, the required identifier type, and an important expansion option. The absence of an output schema is mitigated by the tool's simple nature. It lacks details on optional fields, but these are secondary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It clarifies that work_item_id is a UUID and gives useful values for expand. However, it does not explain project_id or the fields parameter, leaving some semantics to be inferred from parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a single work item by UUID, with a specific verb and resource. It explicitly distinguishes itself from the sibling tool retrieve_work_item_by_identifier, eliminating ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance: use this tool when you have a UUID, and use retrieve_work_item_by_identifier when you have a human-readable key like DEV-42. It also recommends the expand parameter for fuller details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a work item by its human-readable identifier (e.g. "DEV-42"). Provide the project identifier (e.g. "DEV") and the issue sequence number (e.g. 42).
| Name | Required | Description | Default |
|---|---|---|---|
| expand | No | ||
| fields | No | ||
| order_by | No | ||
| external_id | No | ||
| external_source | No | ||
| issue_identifier | Yes | The issue sequence number (e.g. 42). | |
| project_identifier | Yes | The project identifier prefix (e.g. "DEV"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that the lookup uses a human-readable identifier rather than an internal ID, which is helpful. However, it does not describe behavior such as not-found handling, response format, or any side effects beyond the annotation context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences deliver the core purpose and input format with a concrete example. There is no redundant or filler content, and the message is front-loaded with the primary action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a basic retrieve call, but with seven parameters and no output schema, the optional parameters remain undocumented and unclear. It does not state return values or error behavior, so agents may not know about response-fetching options like fields or expand. This is a moderate completeness gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is low (29%), and the description compensates by explaining the two required parameters with concrete examples and clarifying the 'DEV-42' composite format. Yet the five optional parameters (expand, fields, order_by, external_id, external_source) receive no explanation in either the schema or the description, leaving agents without guidance on their semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves a work item by its human-readable identifier (e.g., 'DEV-42'), which distinguishes it from sibling tools like retrieve_work_item (likely by internal ID) and search_work_items. The verb 'retrieve' and the resource 'work item' make the purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context by requiring a project identifier and issue sequence number, implying use when a human-readable ID is known. However, it does not explicitly contrast with alternatives like retrieve_work_item or search_work_items, nor does it state when not to use it. Guidance is clear for the basic case but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single comment by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| comment_id | Yes | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description does not need to restate safety. However, it adds no behavioral context beyond the action itself, such as return format, error behavior, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, but it under-specifies the tool's requirements. It is appropriately short but lacks the detail needed for the structured fields.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With three required parameters and no output schema, the description should explain the return value and the role of each parameter. It only states the basic function, leaving significant gaps in understanding the tool's complete behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage and all three parameters (project_id, work_item_id, comment_id) are undocumented. The description only mentions 'by ID' without clarifying which ID or the relationship between parameters, failing to compensate for the lack of schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool retrieves a single comment by ID, providing a specific verb and resource. However, it does not explicitly differentiate from sibling tools like list_work_item_comments, and 'by ID' is ambiguous given the three required ID parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as list_work_item_comments or other retrieve tools. The description lacks any context about prerequisites, exclusions, or preferred use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a single link by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| link_id | Yes | ||
| project_id | Yes | ||
| work_item_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is known. The description adds no behavioral context beyond that, such as not-found behavior, response format, or relationship between identifiers. It does not contradict annotations, but also fails to disclose any traits not captured by them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant words, making it easy to parse. However, it is so brief that it borders on under-specification, but it does state the core action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a retrieval tool with no output schema, the description does not explain what is returned or how the three IDs relate. The annotations provide safety but not completeness. An agent can select the tool but may not know how to correctly populate parameters or interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions for link_id, project_id, or work_item_id (0% schema coverage). The description only says 'by ID' and does not explain the meaning or purpose of the three required parameters, leaving the agent to infer their roles from the tool name and sibling context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action ('Retrieve') on a resource ('a single link') with an identifier ('by ID'), distinguishing it from list operations like list_work_item_links. However, it does not explicitly differentiate from sibling retrieve tools such as retrieve_work_item_comment, nor does it mention 'work item' in the description, relying on the tool name for context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like list_work_item_links or retrieve_work_item. There are no exclusions, prerequisites, or context indicating the relationship between project_id, work_item_id, and link_id.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for work items by text query. Matches against item names, sequence IDs, and project identifiers. Searches the entire workspace unless project_id is given. Results contain summary fields only (name, id, sequence_id, project identifier); use retrieve_work_item for full details. When linking to a work item, use the format: {PLANE_BASE_URL}/{workspace_slug}/browse/{project_identifier}-{sequence_id}/
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results to return (default 10). | |
| query | Yes | The search text to look for in work items. | |
| project_id | No | Restrict the search to a single project by its UUID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint/openWorldHint annotations, the description adds meaningful behavioral context: results contain summary fields only, matches cover names/sequence IDs/project identifiers, and it provides the linking URL format. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no fluff. Each sentence delivers essential information: action/scope, matching fields, result field limitations, and a practical linking format. It is front-loaded with the primary purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with no output schema and 3 parameters, the description covers the key aspects: what is searched, result scope, result field limitations, and guidance for full details. It is comprehensive without needing an output schema to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds extra meaning: query matches against item names, sequence IDs, and project identifiers, and project_id restricts the scope to a single project. This goes beyond the schema's generic descriptions, though limit is not mentioned in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for work items by text query, specifying what it matches against (names, sequence IDs, project identifiers). It distinguishes itself from sibling tools like list_work_items (which lists without text query) and retrieve_work_item (which provides full details).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says the search covers the entire workspace unless project_id is given, giving clear scope guidance. It also directs users to use retrieve_work_item for full details, providing an explicit alternative for a different use case.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Transfer incomplete work items from one cycle to another. The cycle_id is the source cycle; new_cycle_id is the destination.
| Name | Required | Description | Default |
|---|---|---|---|
| cycle_id | Yes | ||
| project_id | Yes | ||
| new_cycle_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds behavioral context beyond annotations by clarifying the move semantics (source and destination) and the 'incomplete' filtering, which is not present in annotations. It aligns with readOnlyHint=false and destructiveHint=false, with no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences deliver the core purpose and parameter roles without waste. The description is front-loaded with the primary action and immediately clarifies parameter semantics, earning a perfect score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple three-parameter move operation, the description is mostly complete, covering the main intent and the roles of two parameters. Missing project_id semantics and return behavior (no output schema) are minor gaps given the tool's low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explains cycle_id as the source and new_cycle_id as the destination, providing meaning beyond the schema. However, the required project_id parameter is not described, and since schema coverage is 0%, the description should compensate more fully—covering all three parameters rather than only two.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Transfer incomplete work items from one cycle to another' with a clear verb and resource, and specifies scope ('incomplete'). This distinguishes it from sibling tools like add_work_items_to_cycle and remove_work_item_from_cycle by implying a move operation rather than an add/remove.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies when to use the tool (moving incomplete work items between cycles) and provides context via the source/destination parameter roles. However, it does not explicitly contrast with alternatives or mention exclusions like completed items staying behind, so it lacks explicit 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.
Update a cycle by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| cycle_id | Yes | ||
| end_date | No | ||
| owned_by | No | ||
| timezone | No | ||
| project_id | Yes | ||
| start_date | No | ||
| description | No | ||
| external_id | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate this is a non-read-only, non-destructive operation, which aligns with 'update'. However, the description adds no context about important behavioral traits such as whether this is a partial update (patch) or full replacement, or what happens to omitted fields. This ambiguity is not covered by annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero wasted words. It efficiently communicates the essential action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters, no parameter descriptions, and no output schema, the description is far too minimal. It omits details about update semantics, return value, and error conditions, leaving the agent to make assumptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description provides no parameter explanations. Parameter names like 'start_date' and 'external_source' are somewhat self-explanatory, but the description does not clarify semantics like null behavior (clearing fields vs. ignoring them) or the purpose of required project_id alongside cycle_id.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('update') and resource ('cycle'), and 'by ID' indicates targeted modification. This distinguishes it from sibling tools like create_cycle, delete_cycle, and list_cycles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage (when you need to update a cycle), but does not provide explicit when-to-use versus alternatives, prerequisites, or exclusions. It relies on the tool's name and basic semantics.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an epic by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| point | No | ||
| state | No | ||
| labels | No | ||
| parent | No | ||
| epic_id | Yes | ||
| type_id | No | ||
| is_draft | No | ||
| priority | No | ||
| assignees | No | ||
| project_id | Yes | ||
| sort_order | No | ||
| start_date | No | ||
| external_id | No | ||
| target_date | No | ||
| estimate_point | No | ||
| external_source | No | ||
| description_html | No | ||
| description_stripped | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already state readOnlyHint=false and destructiveHint=false. The description adds no behavioral context beyond that, such as whether updating replaces fields, whether null values clear them, or any authorization requirements. It does not contradict the annotations but contributes no incremental transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or repetition. It is concise and to the point, though it sacrifices useful details and is slightly underwhelming for such a parameter-heavy tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a complex 19-parameter update tool with no output schema and minimal annotations. The one-sentence description does not list updatable fields, explain optional/nullable behavior, or describe the response. It is severely 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.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for 19 parameters. The description only mentions 'by ID' and does not name any updatable fields, their types, or formats. This completely fails to compensate for the lack of parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an epic by ID' clearly states the verb (update), resource (epic), and identifier (ID). It is specific enough to distinguish from sibling update tools like update_work_item and update_project.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It only implies usage through the verb 'update' and does not mention related tools like create_epic, retrieve_epic, or delete_epic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an initiative by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| lead | No | ||
| name | No | ||
| state | No | ||
| end_date | No | ||
| logo_props | No | ||
| start_date | No | ||
| initiative_id | Yes | ||
| description_html | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Although annotations already indicate readOnlyHint=false and destructiveHint=false, the description adds no behavioral context such as partial update semantics, required permissions, or return value. It merely states the action without disclosing any behavior beyond what the annotations provide, so it does not meet the bar for adding value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler words. It states the core purpose efficiently and earns its place without unnecessary detail, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters, no output schema, and no usage or behavioral details, this description is severely inadequate. It gives no information about what fields can be updated, how the update behaves, or what the response contains, leaving the agent without essential context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description must compensate by explaining parameters. It only mentions 'by ID', which is redundant given the required initiative_id in the schema. The other 7 parameters (lead, name, state, end_date, logo_props, start_date, description_html) have no explanation in either the schema or the description, providing no added meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Update' with a clear resource 'initiative' and scoping phrase 'by ID'. This clearly distinguishes it from sibling tools like create_initiative, retrieve_initiative, and delete_initiative, meeting the 5-point criteria for specific verb+resource and sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention that this is for modifying an existing initiative, nor does it contrast with create_initiative or retrieve_initiative. There is no context or exclusions, so it earns a 2 for lacking any usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a label by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| color | No | ||
| parent | No | ||
| label_id | Yes | ||
| project_id | Yes | ||
| sort_order | No | ||
| external_id | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds no extra behavioral context. It does not explain whether updates are partial or full, how optional fields behave, or what side effects occur beyond the label being updated. No contradiction with annotations exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundant words. It is appropriately brief, though the extreme terseness sacrifices helpful detail that could be added without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters, 2 required fields, no output schema, and zero parameter descriptions, a one-sentence description is insufficient. An agent cannot determine how to construct a correct update call, including whether all fields are required or how optional fields are applied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only references 'by ID' (label_id), omitting required project_id and all optional fields. Property names like name and color are self-evident, but the semantics of optional null values and partial update behavior are completely undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update'), the resource ('a label'), and the method ('by ID'). This distinguishes it from sibling tools like create_label, retrieve_label, and delete_label.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives, nor does it mention prerequisites such as the label must exist or that project_id is required. Usage is only implied by the verb 'update'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a milestone by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| project_id | Yes | ||
| external_id | No | ||
| target_date | No | ||
| milestone_id | Yes | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not add any behavioral context beyond what annotations already convey. It does not disclose partial update semantics, handling of missing IDs, return values, or side effects, even though annotations only provide readOnlyHint and destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the main action. It avoids fluff, but the extreme brevity leaves out necessary context, making it appropriately sized only for an extremely trivial tool, which this is not.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an update tool with six parameters and no output schema, the description is critically under-specified. It does not explain which fields can be updated, whether the update is partial or full, or what the response contains, leaving significant gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description had the full responsibility to clarify parameters, but it does not mention any of the six properties (title, external_id, target_date, external_source, project_id, milestone_id). The agent receives no insight into what these fields mean or how they are used during the update.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a milestone by ID' clearly states the verb (update) and resource (milestone), and specifies the identifier scope. It is not a tautology and is distinguishable from sibling tools like delete_milestone or retrieve_milestone, though it does not elaborate on what aspects 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.
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, prerequisites, or typical scenarios. The description does not mention exclusions or related tools, leaving the agent to infer context from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a module by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| lead | No | ||
| name | No | ||
| status | No | ||
| members | No | ||
| module_id | Yes | ||
| project_id | Yes | ||
| start_date | No | ||
| description | No | ||
| external_id | No | ||
| target_date | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate it is a write operation (readOnlyHint=false) and non-destructive (destructiveHint=false), but the description adds no context about update semantics (e.g., partial vs full update), validation, or return values. The one-line description merely restates the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short, front-loaded sentence with no filler. However, it is extremely terse, bordering on under-specification, but the conciseness itself is not flawed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (11 params, no schema descriptions, no output schema), the description is severely incomplete. It does not explain behavior, required fields, error conditions, or what the update affects, making it insufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description fails to explain any of the 11 parameters beyond implying module_id is used. It does not mention required project_id, optional fields like name/status/dates, or that parameters likely default to null.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates a module by ID, with a specific verb and resource. It is distinct from sibling tools like create_module or delete_module, though it doesn't describe the scope of fields that 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied from the name and description: it is for modifying an existing module. However, there is no explicit guidance on when to use it versus create or delete, nor any prerequisites like 'module must exist'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a project by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| emoji | No | ||
| close_in | No | ||
| estimate | No | ||
| timezone | No | ||
| page_view | No | ||
| archive_in | No | ||
| cycle_view | No | ||
| identifier | No | ||
| project_id | Yes | ||
| cover_image | No | ||
| description | No | ||
| external_id | No | ||
| intake_view | No | ||
| module_view | No | ||
| project_lead | No | ||
| default_state | No | ||
| external_source | No | ||
| default_assignee | No | ||
| issue_views_view | No | ||
| is_issue_type_enabled | No | ||
| guest_view_all_features | No | ||
| is_time_tracking_enabled | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already convey. It doesn't disclose side effects, whether updates are partial or full, authorization requirements, or return values.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at one short sentence, front-loaded with the action and identifier. It is efficiently written, though it lacks the detail needed for such a complex tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 23 parameters, no output schema, and sparse annotations, this description is severely under-specified. An agent would not know what fields are updatable, how to format values, or what response to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero schema description coverage and 22 optional parameters, the description does nothing to explain the meaning or usage of these fields. It only mentions the project ID, which is already obvious from the schema and required.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('project'), with the identifier requirement ('by ID'). This distinguishes it from sibling tools like retrieve_project, 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.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, exclusions, or related tools such as create_project for new projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a state by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| color | No | ||
| group | No | ||
| sequence | No | ||
| state_id | Yes | ||
| is_triage | No | ||
| project_id | Yes | ||
| description | No | ||
| external_id | No | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false, so the agent knows this is a non-destructive write. However, the description adds no behavioral detail—no partial vs full update semantics, effects of null fields, permissions, or response behavior. It does not contradict annotations but offers no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence, but it is under-specified for a tool with 10 parameters. It is terse rather than appropriately concise, omitting essential context that the agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
There is no output schema, annotations are minimal, and the input schema has 10 parameters. A one-sentence description is insufficient to explain return values, required context, or update behavior, making correct invocation unlikely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description only mentions 'by ID' without identifying state_id/project_id or any of the 8 optional fields. With 10 parameters and no parameter-level explanation, the agent cannot infer what properties can be updated.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update') and the resource ('state'), and the 'by ID' gives a scoping hint. This distinguishes it from sibling tools like create_state, delete_state, and retrieve_state, though it does not enumerate which fields 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.
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 create_state/delete_state, exclude scenarios, or state prerequisites. Usage is only implied by the word 'Update'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing work item. Only include fields you want to change — omitted fields are left unchanged. Use list_states for state_id, get_workspace_members for assignee UUIDs, list_labels for label UUIDs.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| labels | No | ||
| type_id | No | ||
| priority | No | ||
| state_id | No | ||
| assignees | No | ||
| parent_id | No | ||
| project_id | Yes | ||
| sort_order | No | ||
| start_date | No | ||
| external_id | No | ||
| target_date | No | ||
| work_item_id | Yes | ||
| estimate_point | No | ||
| external_source | No | ||
| description_html | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=false. The description adds useful behavioral context by revealing that omitted fields are left unchanged, which is critical for update semantics. It does not go deeper into authorization or error behavior, but it adds value beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and immediately followed by the most important behavioral rule and ID-resolving hints. Every sentence earns its place; no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 16 parameters and no output schema, so the description carries significant responsibility. It covers update semantics and ID lookups, but does not clarify formats or allowed values for fields like priority, dates, sort_order, or estimate_point. This leaves some ambiguity for an agent attempting correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 16 parameters with 0% description coverage. The description helps for three specific parameters (state_id, assignees, labels) by pointing to lookup tools and indicating UUIDs. However, many other parameters (priority, dates, parent_id, external_id, etc.) are left unexplained, so the description only partially compensates for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description begins with 'Update an existing work item,' which clearly identifies the verb and resource. This distinguishes it from create_work_item, retrieve_work_item, and delete_work_item among the sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the partial-update behavior ('Only include fields you want to change — omitted fields are left unchanged') and tells the agent which sibling tools to use for resolving IDs (list_states, get_workspace_members, list_labels). It does not exclude alternative tools, but the update semantics and resource-lookup guidance are clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a comment on a work item.
| Name | Required | Description | Default |
|---|---|---|---|
| comment_id | Yes | ||
| project_id | Yes | ||
| external_id | No | ||
| comment_html | No | ||
| work_item_id | Yes | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already convey (readOnlyHint=false, destructiveHint=false). It does not explain the effects of updating, such as whether the entire comment is replaced or if optional fields like external_id are used for locating the comment. The openWorldHint=true is also left unexplained, and the description simply restates the tool's name.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of a single sentence with no redundant words. It is front-loaded and readable. However, it is so brief that it sacrifices substance, making it less useful than a slightly longer, more informative description.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, 3 required, and no output schema, the one-sentence description is insufficient. It does not explain the meaning of optional fields, the effect of null values, or how the comment is identified. The description lacks the detail needed for reliable invocation, especially without parameter descriptions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description must compensate by explaining parameters. It does not mention any of the six parameters (project_id, work_item_id, comment_id, comment_html, external_id, external_source) or their roles. This leaves the agent without any guidance on how to populate the parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description specifies the exact verb ('Update') and resource ('a comment on a work item'), clearly distinguishing this from sibling tools like create_work_item_comment, delete_work_item_comment, and retrieve_work_item_comment. It leaves no ambiguity about the tool's core function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, such as the comment needing to already exist, nor does it differentiate this from create or delete operations. The usage context is only implied by the verb 'Update'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a link on a work item.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| title | No | ||
| link_id | Yes | ||
| project_id | Yes | ||
| external_id | No | ||
| work_item_id | Yes | ||
| external_source | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation), destructiveHint=false (not destructive), and openWorldHint=true. The description adds no behavioral context beyond the act of updating, such as partial update semantics, identifier requirements, or consequences. It does not contradict annotations, but provides no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded, with no redundant wording. However, for a tool with 7 parameters, the brevity crosses into under-specification rather than efficient communication, making it minimally acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete given the tool's complexity. It does not explain what fields can be updated, the meaning of link_id, the relationships among identifiers, or what the openWorldHint implies. No output schema exists, so the description must carry more weight but does not.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description contains no parameter explanations. With 7 parameters including composite identifiers (project_id, work_item_id, link_id) and optional fields (url, title, external_id, external_source), the description fails to compensate for the schema's lack of descriptive text.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a link on a work item' is a specific verb+resource statement that clearly distinguishes this tool from siblings like update_work_item, create_work_item_link, and delete_work_item_link. It identifies the exact operation (update) and target (link on a work item).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives. The description does not mention prerequisites, when an update is appropriate, or contrast with create/retrieve/delete link tools. This is a complete absence of usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Every tool is tied to a specific resource and action (e.g., list_states vs. create_state, list_cycle_work_items vs. add_work_items_to_cycle). Despite the volume, the entity names make each tool's purpose immediately clear, and there is no overlap or ambiguity between tools.
The dominant pattern is verb_noun (list_*, create_*, retrieve_*, update_*, delete_*), but a few tools use 'get' instead of 'retrieve' (e.g., get_server_version, get_project_members, get_workspace_members, get_me). The inconsistency is minor and does not impede understanding.
With 78 tools, the server is much larger than typical MCP servers, making it heavy for agents to navigate. While the breadth matches the extensive domain (projects, work items, cycles, modules, epics, etc.), the count is excessive and risks overwhelming users.
The server covers CRUD for nearly all major resources (projects, work items, states, labels, cycles, modules, epics, milestones, initiatives, comments, links, relations). The only notable gap is pages, which only have create and retrieve—no update, delete, or list—representing a minor dead end.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Connect Claude to your Platform7n workspaces — chat, links, and tasks. One-click OAuth.
One workspace of tools for Claude and ChatGPT: connect 600+ apps, generate media, build tools.
Connect Claude AI to UluP Spaces via MCP — create projects, nodes, and tasks with OAuth 2.0.
AI-native Kanban board — connect Claude to claim, work and move your tasks over MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/ZethicTech/plane-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
