Provides tools for interacting with Linear's API, enabling management of issues, projects, and teams programmatically through the Linear platform.
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., "@Linear MCP Server create a new issue for the login bug"
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.
An MCP server for interacting with Linear's API. This server provides a set of tools for managing Linear issues, projects, and teams through Cline.
You can use either a Developer Token or a Personal API Key.
Option 1: Developer Token
Go to Linear: Workspace Settings > API > OAuth application > Create or select an application (e.g., "Cline MCP").
Under "Developer Token", click "Create & copy token".
Select "Application" as the actor and copy the generated token.
Option 2: Personal API Key
Go to Linear: Your Personal Settings > API > Personal API Keys.
Click "Create key", give it a label (e.g., "Cline MCP"), and copy the generated key.
Open your Cline MCP settings file:
macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %APPDATA%/Code/User/GlobalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Add the Linear MCP server configuration:
{
"mcpServers": {
"linear": {
"command": "npx",
"args": ["-y", "mcp-server-linear"],
"env": {
"LINEAR_ACCESS_TOKEN": "your_linear_api_token_here"
},
"disabled": false,
"autoApprove": []
}
}
}That's it! The server will be automatically downloaded and run through npx when needed.
If you use Cline/Roo, you can also simply tell it install the MCP from https://github.com/dvcrn/mcp-server-linear and it'll do the rest.
Related MCP server: Linear MCP Server
The server currently supports the following operations:
✅ Create issues with full field support (title, description, team, project, parent/child relationships, etc.)
✅ Update existing issues (priority, description, etc.)
✅ Delete issues (single or bulk deletion)
✅ Search issues with filtering and by identifier
✅ Associate issues with projects
✅ Create parent/child issue relationships
✅ Comment management (create, update, delete comments)
✅ Comment resolution handling (resolve/unresolve comments)
✅ Create customer needs from attachments
✅ Create projects with associated issues
✅ Get project information
✅ List all projects with optional filtering
✅ Associate issues with projects
✅ Project milestone management (create, update, delete)
✅ List and filter project milestones
✅ Get team information (with states and workflow details)
✅ Access team states and labels
✅ Personal Access Token (PAT) authentication
✅ Secure token storage
✅ Bulk issue creation
✅ Bulk issue deletion
🚧 Bulk issue updates (parallel processing implemented, needs testing)
The following features are currently being worked on:
🚧 Complex search filters
🚧 Pagination support for large result sets
🚧 Label management (create/update/assign)
✅ Project milestone management
🚧 Project template support
🚧 Advanced project operations
🚧 OAuth flow with automatic token refresh
🚧 Rate limiting
🚧 Detailed logging
🚧 Load testing and optimization
The server supports creating and managing hierarchical relationships between issues:
You can create sub-issues by specifying a parent issue's UUID when creating a new issue:
{
"title": "Sub-task Implementation",
"description": "Implement this specific part of the parent task",
"teamId": "team_uuid",
"parentId": "parent_issue_uuid"
}Note: The parentId must be the UUID of the parent issue, not the issue identifier (e.g., use the UUID, not "ENG-123").
You can connect to multiple Linear workspaces by adding the Linear MCP server multiple times with different TOOL_PREFIX values. This allows you to work with separate Linear workspaces within the same Cline environment.
{
"mcpServers": {
"company1-linear": {
"command": "npx",
"args": ["mcp-server-linear"],
"env": {
"LINEAR_ACCESS_TOKEN": "your_company1_linear_token_here",
"TOOL_PREFIX": "company1"
},
"disabled": false,
"autoApprove": []
},
"company2-linear": {
"command": "npx",
"args": ["mcp-server-linear"],
"env": {
"LINEAR_ACCESS_TOKEN": "your_company2_linear_token_here",
"TOOL_PREFIX": "company2"
},
"disabled": false,
"autoApprove": []
},
"company3-linear": {
"command": "npx",
"args": ["mcp-server-linear"],
"env": {
"LINEAR_ACCESS_TOKEN": "your_company3_linear_token_here",
"TOOL_PREFIX": "company3"
},
"disabled": false,
"autoApprove": []
}
}
}When you set a TOOL_PREFIX value:
All tool names are prefixed with it (e.g., company1_linear_create_issue)
Tool descriptions include the prefix (e.g., "For 'company1' Linear workspace: Create a new issue")
This makes it clear which workspace each tool is operating on and prevents conflicts between different Linear instances.
If you want to contribute to the development of this MCP server, follow these steps:
Clone the repository
Install dependencies:
npm installCopy .env.example to .env:
cp .env.example .envAdd your Linear API token to .env:
LINEAR_ACCESS_TOKEN=your_personal_access_token# Install dependencies
npm install
# Run tests
npm test
# Build and run the server locally
npm run build
npm start
# Or use development mode with auto-reload
npm run devIntegration tests verify that authentication and API calls work correctly:
Set up authentication in .env (PAT recommended for testing)
Run integration tests:
npm run test:integrationFor OAuth testing:
Configure OAuth credentials in .env:
LINEAR_CLIENT_ID=your_oauth_client_id
LINEAR_CLIENT_SECRET=your_oauth_client_secret
LINEAR_REDIRECT_URI=http://localhost:3000/callbackRemove .skip from OAuth tests in src/__tests__/auth.integration.test.ts
Run integration tests
Handle OAuth callback
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | OAuth authorization code |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It only says 'Handle OAuth callback' without detailing what side effects occur (e.g., token creation, session setup), error conditions, or whether it is idempotent. This is insufficient for an AI agent to understand behavioral implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with one short sentence. It is front-loaded and not verbose, though it could be improved by slightly expanding to include key 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's simplicity (one parameter, no output schema), the description should at least mention that this completes OAuth authentication and may return tokens. It lacks mention of return value or error handling, making it incomplete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description does not add any additional meaning beyond the schema's 'OAuth authorization code' for the 'code' parameter. Baseline is 3 since schema fully describes the parameter.
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 'Handle OAuth callback' clearly states the tool's purpose with a specific verb and resource. It distinguishes from other sibling tools which are all Linear API operations, none of which are OAuth-related.
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 or when not to use this tool compared to alternatives. While the context implies it should be used after an OAuth redirect, there is no explicit instruction or mention of prerequisites like a state parameter for CSRF protection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update multiple issues at once
| Name | Required | Description | Default |
|---|---|---|---|
| issueIds | Yes | List of issue UUIDs to update (not issue identifiers like 'ENG-123') | |
| update | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose behavioral traits such as atomicity, partial failure behavior, idempotency, or concurrency. The simple statement 'Update multiple issues at once' lacks depth.
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 (4 words) but not tautological. It could include more context without sacrificing conciseness, but it is front-loaded 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?
Given complexity (nested object, no output schema, no annotations, 2 required params), the description is incomplete. It does not cover return values, error handling, rate limits, or prerequisites for using the 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?
Schema coverage is 50% but the input schema includes descriptions for all parameters (issueIds, update with nested properties). The description adds no extra meaning beyond the schema; baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update multiple issues at once' clearly states the action (update), resource (issues), and scope (multiple/at once). It distinguishes from sibling tools like linear_edit_issue (single issue) and linear_create_issues (create).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., linear_edit_issue for single updates). Missing when-not-to-use or prerequisites. The scope 'at once' is implied but not explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new comment on an issue
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | Comment text content | |
| issueId | Yes | ID of the issue to comment on |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It only says 'creates a new comment', implying mutation, but does not disclose permissions, limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, concise but not adding value beyond the name. It could incorporate more context 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?
For a simple create tool without output schema and no annotations, the description is minimal but covers the basic action. However, sibling tools exist, so more context on behavior or response would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for both parameters, providing baseline clarity. The description adds no extra parameter context beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a comment on an issue (verb+resource), but does not differentiate from sibling tools like linear_update_comment or linear_resolve_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 on when to use this tool versus alternatives (e.g., linear_update_comment or linear_delete_comment). The description is a simple statement with no context for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new customer need from an attachment
| Name | Required | Description | Default |
|---|---|---|---|
| attachmentId | Yes | ID of the attachment | |
| title | No | Title for the customer need | |
| description | No | Description for the customer need | |
| teamId | No | Team ID for the customer need |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It only states the action (creates) without disclosing side effects, required permissions, or what happens to the attachment. Critical behavioral details are missing for a creation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence, but it is too short to provide adequate context for a tool with 4 parameters. It is minimally acceptable but could be expanded to include key details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description should explain the purpose of creating a customer need, what the attachment is used for, and potential return values. It falls short of providing a complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already explains each parameter. The description adds no additional meaning beyond what is in the schema, which is acceptable but not extra helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the specific action (creates a new customer need) and source (from an attachment), which is clear and distinct from sibling tools like create_issue or create_comment. However, it lacks context about what a customer need is, which slightly reduces clarity.
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 create_issue or create_comment. There is no indication of prerequisites or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new issue in Linear
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Issue title | |
| description | Yes | Issue description | |
| teamId | Yes | Team ID (UUID) | |
| parentId | No | Parent issue ID (UUID, not issue identifier) | |
| labelIds | No | Label UUIDs to apply, eg ['a1eb5aed-7425-4ea5-98ec-dfab52381e0e'] | |
| assigneeId | No | Assignee user ID (UUID) | |
| priority | No | Issue priority (0-4) | |
| createAsUser | No | Name to display for the created issue | |
| displayIconUrl | No | URL of the avatar to display |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides no behavioral details such as side effects, required permissions, or response behavior. Only states creation without any disclosure of what happens after.
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, which is concise but lacks structure. It does not front-load key information or provide any 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?
With 9 parameters, no output schema, and no annotations, the description is insufficient. It fails to cover behavior, return values, or usage nuances, leaving significant gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no extra meaning or context beyond what's in the schema, meeting the baseline for high 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 'Create a new issue in Linear' clearly states the verb (create) and resource (issue), and distinguishes from siblings like linear_edit_issue and linear_create_issues.
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. Does not mention prerequisites, limitations, or scenarios for choosing this over linear_create_issues or linear_edit_issue.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create multiple issues at once
| Name | Required | Description | Default |
|---|---|---|---|
| issues | Yes | List of issues to create |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description fails to disclose any behavioral traits such as atomicity, error handling, rate limits, or side effects. The single sentence offers no transparency beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but lacks structure and important details. It does not waste words but is under-specified for a complex tool with nested parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (nested array, many optional fields), no output schema, and no annotations, the description is incomplete. It omits return values, error handling, and batch behavior, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds no additional meaning beyond what's in the schema, hence baseline score of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create multiple issues at once' clearly states the verb (create) and resource (multiple issues), and it distinguishes from the sibling tool 'linear_create_issue' which creates a single 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?
No explicit guidance on when to use this tool versus alternatives like 'linear_create_issue'. The description only implies batch usage without providing context on limitations, prerequisites, or scenarios where single issue creation is preferred.
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 milestone
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | Project ID to create milestone for | |
| name | Yes | Milestone name | |
| description | No | Milestone description | |
| targetDate | No | Target completion date (ISO format) | |
| sortOrder | No | Sort order for the milestone |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility for behavioral disclosure. It only states 'create' without revealing side effects, idempotency, or error conditions, which is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It is front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters and no output schema, the description is very brief. It omits important context about how milestones relate to projects, default behavior, and return value. A more complete description would include expected outcomes or usage hints.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description does not need to explain parameters further. However, it adds no additional semantic value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create) and the resource (project milestone), distinguishing it from sibling tools like update and delete. However, it lacks context on what a project milestone represents in Linear.
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 (e.g., existing project). The description offers no context for appropriate usage.
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 with associated issues. Note: Project requires teamIds (array) not teamId (single value).
| Name | Required | Description | Default |
|---|---|---|---|
| project | Yes | ||
| issues | Yes | List of issues to create with this project |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It only clarifies the teamIds format but does not disclose any behavioral traits such as side effects, authentication requirements, rate limits, or what happens to existing data. For a creation tool, this is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence plus a focused note. Every word earns its place, front-loading the core purpose. There is no superfluous text.
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 (nested objects, multiple required parameters), the description is adequate but incomplete. It does not explain return values (no output schema), constraints like team IDs must exist, or that issues' teamId must match a project teamId. More context would help, but it meets the minimum viable standard.
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 already provides descriptions for all parameters, so baseline is 3. The description adds value by explicitly noting that teamIds must be an array (not a single value), which can prevent a common mistake. This goes beyond what the schema states.
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 creates a new project with associated issues, and includes a helpful note distinguishing teamIds (array) from teamId. This uniquely identifies the tool's purpose among siblings like linear_create_issue and linear_create_project_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?
The description implies the tool is for creating projects along with issues, but it does not explicitly state when to use this versus alternatives like linear_create_issues (which creates issues without a project) or linear_create_project (if it existed). No when-not or alternative tools are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deletes a comment
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Comment ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral disclosure. It only states 'Deletes a comment' without mentioning irreversibility, required permissions, or side effects. For a destructive action, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no 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?
For a simple delete operation with one required param and no output schema, the description is mostly complete. However, it lacks details on return value (e.g., success/failure) and behavioral consequences, which would be helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is described in the schema as 'Comment ID to delete'. The description adds no extra meaning beyond what the schema provides. Given 100% schema coverage, a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (deletes) and the resource (a comment). It distinguishes from siblings like linear_create_comment or linear_update_comment. However, it could be more explicit about the scope (e.g., by ID).
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 delete versus alternatives like linear_resolve_comment or linear_update_comment. The agent has no context on appropriate use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete an issue
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Issue UUID (not issue identifier like 'ENG-123') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must convey behavioral traits. It only states 'delete', but fails to disclose consequences like irreversibility, required permissions, or impact on related 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 extremely short (two words) and under-specified. Conciseness is not achieved at the expense of necessary 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 destructive operation with no output schema and no annotations, the description is insufficient. It omits details like idempotency, error scenarios, and expected outcomes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter 'id' is already documented. The description adds no additional 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 'Delete an issue' is essentially a tautology of the tool name, providing no additional specificity. It does not distinguish the tool from sibling delete tools like linear_delete_comment or linear_delete_project_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 provided on when to use this tool versus alternatives. The description lacks any context about recommended use cases or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a project milestone
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Milestone ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits such as irreversibility, cascading effects, or required permissions. With no annotations provided, the description carries the full burden but only states the obvious 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, front-loaded sentence with no redundancy. It earns its place but could be slightly expanded for better completeness without losing 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?
Given the tool's simplicity (one parameter, no output schema), the description is adequate but lacks details on return value, error conditions, or typical behavior. Minimal additions would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, and the parameter 'id' is described as 'Milestone ID to delete'. The description adds no extra meaning beyond the schema; baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a project milestone' clearly states the action (delete) and the resource (project milestone). It effectively distinguishes this tool from sibling tools like create, update, and get 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 on when to use this tool versus alternatives, nor any prerequisites or conditions for safe deletion. The implied usage is clear from the name, but explicit directives are missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit an existing issue, updating any of its fields. Note: When setting projectMilestoneId, you must also set projectId.
| Name | Required | Description | Default |
|---|---|---|---|
| issueId | Yes | Required: The UUID of the issue to update | |
| title | No | The issue title | |
| description | No | The issue description in markdown format | |
| stateId | No | UUID of the target state | |
| priority | No | Issue priority (0=No priority, 1=Urgent, 2=High, 3=Normal, 4=Low) | |
| assigneeId | No | UUID of the user to assign the issue to | |
| labelIds | No | Array of label UUIDs (replaces existing labels) | |
| projectId | No | UUID of the project to associate with the issue | |
| projectMilestoneId | No | UUID of the project milestone to associate with the issue. Note: Requires projectId to be set when using this field | |
| estimate | No | The estimated complexity points for the issue | |
| dueDate | No | The due date in YYYY-MM-DD format | |
| parentId | No | UUID of the parent issue | |
| sortOrder | No | Position of the issue relative to other issues |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries behavioral burden. It mentions the constraint but does not disclose other behaviors like whether updates are atomic, permissions required, or side effects. The schema provides some behavioral details (e.g., labelIds replaces existing), but the description adds little beyond the constraint.
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 plus a note. It is extremely concise, front-loaded, and contains no unnecessary words. Every part is useful.
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 13 parameters and no output schema, the description is minimal. It does not explain return values, error handling, or relationships beyond the noted constraint. The schema fills in details, but the description could provide more context for a complex update 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?
Schema coverage is 100%, so baseline is 3. The description repeats the constraint from the schema for projectMilestoneId, but does not add new meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool edits an existing issue and updates its fields. It distinguishes from sibling tools like linear_create_issue (create) and linear_delete_issue (delete) by implying 'edit' as the 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 a specific constraint: when setting projectMilestoneId, projectId must also be set. This guides correct usage. However, it does not explicitly state when to use this tool versus alternatives like linear_create_issue or linear_bulk_update_issues, though the name and context suggest it is for single-issue updates.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single issue by identifier, including all comments
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes | Issue identifier (e.g., 'ENG-123') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries full burden. It indicates read-only behavior ('Get'), but does not explicitly state safety, authentication needs, or rate limits. Adequate for a simple get 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?
Description is a single, front-loaded sentence with no wasted words. It efficiently conveys the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema) and the context of sibling tools, the description is sufficient. It could hint at response structure but is complete enough for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter description. The description does not add additional meaning to the parameter beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get', the resource 'issue', and the scope 'including all comments'. It distinguishes this tool from siblings like linear_get_issue_comments and linear_search_issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need a single issue with all comments, but does not explicitly mention alternatives or exclusion criteria. Siblings like linear_get_issue_comments exist but are not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Gets comments on a Linear issue by issue UUID or identifier
| Name | Required | Description | Default |
|---|---|---|---|
| issueId | Yes | Linear issue UUID or identifier, e.g. ENG-123 | |
| first | No | Number of comments to return (default: 25) | |
| after | No | Cursor for pagination |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It states it gets comments but does not describe whether results are paginated, sorted, or any side effects. For a read-only operation, more detail about response structure would improve 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 sentence that is front-loaded with the action. It is efficient and free of filler, though it could be slightly more informative without harming 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?
Given the tool has 3 parameters, no output schema, and no annotations, the description is adequate but minimal. It does not mention return format, pagination behavior (though schema hints at it), or that it returns a list. A bit more context would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions, achieving 100% coverage. The tool description adds no additional parameter-level information beyond what the schema provides, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Gets', the resource 'comments on a Linear issue', and the required input 'issue UUID or identifier'. It effectively distinguishes from sibling tools like linear_create_comment (create) and linear_delete_comment (delete).
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 retrieve comments for a specific issue, but lacks explicit guidance on when to use this over alternatives (e.g., linear_search_issues) or when not to use it. No mention of prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get project information
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Project identifier |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description bears full responsibility. It does not disclose behavioral traits such as required permissions, error handling (e.g., if ID is invalid), or data freshness. A simple 'Get' is assumed but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise at one short sentence, which is appropriate for a simple tool. It is front-loaded and easy to scan, but could include more context without harming 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?
Given the tool's simplicity (single required ID, no output schema), the description is minimally complete but lacks behavioral notes or return value hints. It does not explain what project information is returned.
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% with one parameter 'id'. The description adds no meaning beyond the schema's 'Project identifier'. The format or source of the identifier is not clarified, but the schema is sufficient.
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 project information' clearly states the verb (Get) and resource (project information), but does not distinguish from sibling tools like 'linear_list_projects' which lists many projects, or 'linear_get_project_milestones' which concerns milestones.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., 'linear_list_projects' for browsing, 'linear_get_issue' for issues). The description does not mention prerequisites or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get milestones for a project with filtering and pagination
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | Project ID to get milestones for | |
| filter | No | Optional filter criteria | |
| first | No | Number of items to return (used with after) | |
| after | No | Cursor for forward pagination | |
| last | No | Number of items to return (used with before) | |
| before | No | Cursor for backward pagination | |
| includeArchived | No | Include archived milestones | |
| orderBy | No | Field to order by (createdAt or updatedAt) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It mentions filtering and pagination but does not state if the operation is read-only, what happens with invalid projectId, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear, and front-loaded sentence with no unnecessary words. It effectively summarizes the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool having 8 parameters, nested objects, and no output schema, the description does not explain how parameters interact, the output format, or the behavior of pagination and filtering together. More detail is needed for complete 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 coverage is 100%, so each parameter is documented in the input schema. The description adds the high-level concept of filtering and pagination but does not provide additional nuance beyond what the schema already states.
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 verb 'Get' with 'milestones for a project', clearly indicating the resource and action. It distinguishes from sibling tools like create/update/delete milestones by being a read 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?
No explicit guidance on when to use this tool versus alternatives. It does not mention prerequisites or when not to use it, such as for manipulating milestones.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all teams with their states and labels
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description explains that the tool returns 'all teams with their states and labels', indicating a read-only operation. No annotations are provided, so the description carries the full burden, and it adequately discloses the basic behavior, though it does not mention potential pagination or ordering.
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 efficiently conveys the entire purpose and scope. Every word is necessary, and there is no wasted text.
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 tool with no parameters and no output schema, the description is sufficiently complete. It states what is retrieved (all teams with states and labels), which covers the essential information. Minor details like workspace scope or return format could be added but are not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (0 parameters, 100% schema coverage). Per the rubric, a baseline of 4 is appropriate since there is no need for additional parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'get' and the resource 'teams', and specifies what is included ('their states and labels'). It is specific and distinct from sibling tools which deal with issues, projects, comments, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage to retrieve all teams with associated states and labels. There are no direct alternative tools for getting teams among siblings, so no explicit when-not guidance is needed. The clarity of purpose provides sufficient context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current user information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, and the description only says 'information' without clarifying read-only nature, authentication needs, or output specifics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, but could include more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no parameters and no output schema, the description fails to explain what user information is returned, leaving the agent unsure of the return value.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description does not need to add parameter meaning; baseline 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 it gets current user information, which is specific and distinct from siblings like linear_get_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?
No guidance on when to use this tool versus alternatives, no prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects or filter them by criteria
| Name | Required | Description | Default |
|---|---|---|---|
| filter | No | Optional filter criteria for projects |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description only states the basic function, without disclosing behavioral traits such as pagination, rate limits, required permissions, or default behavior when no filter is provided.
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 that efficiently conveys the tool's purpose. It is concise but could include more context 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 no output schema and a nested filter parameter, the description is minimal. It does not explain return format or pagination. The schema covers filter details, but behavioral context is lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no additional meaning beyond the schema, merely stating 'filter them by criteria'. The schema already describes the filter structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'projects', and mentions filtering. It distinguishes from sibling tools like linear_get_project, which retrieves a single 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 implies usage for listing projects, but does not explicitly state when to use this tool versus alternatives like linear_get_project. No guidance on when not to use or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resolves a comment
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Comment ID to resolve | |
| resolvingCommentId | No | Optional ID of a resolving comment |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full burden. It only states 'Resolves a comment' without disclosing effects, reversibility, or side effects. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, using a single front-loaded sentence. It is efficient but could benefit from additional context without sacrificing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 parameters, no output schema, no annotations, and sibling tools, the description is incomplete. It does not explain what 'resolve' entails or the role of the optional parameter.
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%, with clear descriptions for both parameters. The tool description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Resolves a comment' clearly states the action and resource, using a specific verb. It distinguishes from sibling tools like linear_unresolve_comment through the name, though the description itself does not explicitly differentiate.
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 siblings like linear_update_comment or linear_delete_comment. The description lacks context for selecting the appropriate tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for issues with filtering and pagination
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | Search query string | |
| teamIds | No | Filter by team IDs | |
| assigneeIds | No | Filter by assignee IDs | |
| states | No | Filter by state names | |
| priority | No | Filter by priority (0-4) | |
| first | No | Number of issues to return (default: 50) | |
| after | No | Cursor for pagination | |
| orderBy | No | Field to order by (default: updatedAt) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description must carry the full burden. It mentions 'filtering and pagination' but does not disclose any behavioral traits such as authentication requirements, rate limits, or the behavior when no filters are applied. The description adds minimal value beyond what the name and schema imply.
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, which is concise. However, its brevity comes at the cost of completeness. It is appropriately structured but lacks necessary 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?
With 8 parameters and no output schema, the description is incomplete. It does not explain the return structure, pagination semantics (e.g., how to use 'after' cursor), or error handling. For a complex search tool, the description should provide more context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description does not add meaning beyond the schema; it merely reiterates 'filtering and pagination' without explaining parameter combinations or expected formats.
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 'search' and resource 'issues', indicating a search operation. However, it does not differentiate from sibling tool 'linear_search_issues_by_identifier', as it lacks specificity about the type of search (general vs. identifier-based).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidelines are provided. The description does not indicate when to use this tool over alternatives like 'linear_search_issues_by_identifier' or when not to use it. The agent is left to infer context from the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for issues by their identifiers (e.g., ["ENG-78", "ENG-79"])
| Name | Required | Description | Default |
|---|---|---|---|
| identifiers | Yes | Array of issue identifiers to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It correctly indicates a search operation (read-only), but does not disclose traits like maximum number of identifiers, reaction to missing identifiers, or whether results are complete or truncated.
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: one line with an example. Every word is necessary; no 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 tool with one parameter and no output schema, the description is mostly complete. It communicates the core function and input format. However, a note on return values (e.g., that it returns full issue objects) would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage for the 'identifiers' parameter. The description adds value by showing an example format (['ENG-78', 'ENG-79']), clarifying the expected string pattern and array style.
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 'Search for issues by their identifiers' which is a clear and specific verb-resource combination. The example format further clarifies the expected input. Additionally, the presence of sibling 'linear_search_issues' implies a distinction, and this tool's focus on identifiers makes it distinct.
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 does not provide guidance on when to use this tool versus alternatives like 'linear_search_issues'. No when-not-to-use or prerequisites are mentioned. Given the sibling tool exists for broader searches, explicit context would be helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unresolves a comment
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Comment ID to unresolve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It only states the action without disclosing side effects, idempotency, or required permissions. The behavioral impact (unresolving a comment) is implied but not elaborated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise, consisting of a single sentence that immediately conveys the purpose. However, it may be overly brief, lacking additional context that could improve usability.
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 no output schema and one parameter, the description is minimal. It does not explain the relationship to resolving comments or the expected outcome, leaving gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for the 'id' parameter. The tool description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Unresolves a comment' clearly states the verb and resource, making the tool's purpose obvious. However, it does not differentiate from sibling tools like linear_resolve_comment, though the name itself provides that distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives (e.g., linear_resolve_comment or linear_delete_comment). The description lacks any context about prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates an existing comment
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Comment ID | |
| input | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; the description does not disclose side effects, permissions, idempotency, or return behavior. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short but lacks necessary detail. It is not overly verbose, but the brevity sacrifices informativeness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of output schema and annotations, the description is incomplete. It does not mention return values, required permissions, or any constraints beyond the tool name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (id has description, input does not at the parameter level). The description adds no explanation of parameters, failing to compensate for the 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 'Updates an existing comment' clearly states the action (update) and the resource (comment). It distinguishes from create and delete, but doesn't specify what fields are updated or the exact behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs siblings like create, delete, resolve, or unresolve. The description lacks any context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a project milestone
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Milestone ID to update | |
| name | No | New milestone name | |
| description | No | New milestone description | |
| targetDate | No | New target completion date (ISO format) | |
| sortOrder | No | New sort order |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks any behavioral details beyond the fact that it performs an update. With no annotations provided, the description should disclose side effects, authentication requirements, or idempotency, but it does not.
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, which is concise but lacks structure or front-loading of key information. Every word earns its place, but it could be better organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has 5 parameters and no output schema or annotations, the description is incomplete. It does not explain return values, constraints, or behavior, making it insufficient for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for each parameter, so the baseline is 3. The description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and the resource 'a project milestone', which is specific and distinguishes from sibling tools like create or delete. However, it could be more descriptive about what aspects are 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 (e.g., linear_bulk_update_issues for bulk updates, or other sibling tools). There is no mention of prerequisites or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v1.6.0linear_auth_callbacklinear_bulk_update_issueslinear_create_commentlinear_create_customer_need_from_attachmentlinear_create_issuelinear_create_issueslinear_create_project_milestonelinear_create_project_with_issueslinear_delete_commentlinear_delete_issuelinear_delete_project_milestonelinear_edit_issuelinear_get_issuelinear_get_issue_commentslinear_get_projectlinear_get_project_milestoneslinear_get_teamslinear_get_userlinear_list_projectslinear_resolve_commentlinear_search_issueslinear_search_issues_by_identifierlinear_unresolve_commentlinear_update_commentlinear_update_project_milestoneMost tools have distinct purposes, but `linear_get_issue` includes comments while `linear_get_issue_comments` is separate, causing potential confusion. Otherwise, all tools are well-differentiated.
All tools follow a consistent `linear_verb_noun` snake_case pattern, making it easy to predict functionality from names.
25 tools is on the high side but justified by the breadth of Linear's features (issues, projects, milestones, comments, etc.). Some redundancy (e.g., separate create_issue and create_issues) could be consolidated.
Covers most CRUD operations for core entities, but lacks project deletion and update, and has no simple list-issues endpoint (only search). Minor gaps that agents may need to work around.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Linear project management and issue tracking
Linear MCP — wraps the Linear GraphQL API (OAuth)
Search, read and create Linear issues, projects, teams and cycles.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/10xtechnology/linear-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
