linear

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations; description labels it as WRITE/MUTATING but does not disclose side effects, response format, or any constraints beyond required params.

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 warning, no fluff. 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?

Minimal but covers key points for a simple 2-param tool. Missing return value info, but acceptable given simplicity.

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 100%, description adds clarity: issueId is UUID (not display ID), body is markdown. Adds value beyond 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?

Clearly states it posts a comment on an issue, uses specific verb+resource. Distinguishes from siblings which are about creating issues, listing, 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?

Implied usage: use when you need to add a comment to an issue. No explicit when-not-to-use or alternatives given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explicitly marks it as 'WRITE / MUTATING' and mentions 'GraphQL: mutation issueCreate', indicating that it modifies data. Since no annotations are provided, the description fully carries the burden of behavioral 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 a single concise sentence covering the purpose and key parameters. It could be slightly more structured (e.g., breaking out optional fields), but it is not verbose and front-loads the mutation warning.

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 full schema coverage, no output schema, and 5 parameters, the description sufficiently explains what the tool does and what is required. It mentions the critical dependency on linear_list_teams for teamId.

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 has descriptions for all 5 parameters (100% coverage), so the description adds minimal extra meaning beyond restating the priority scale and mentioning markdown for description, which is already in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it creates a new issue in Linear, using the verb 'creates' and specifying the resource 'issue'. It distinguishes from sibling tools like linear_get_issue (read) or linear_search_issues (search) by explicitly labeling it as a write/mutating 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?

It specifies that teamId is required and must come from linear_list_teams, providing a clear prerequisite. It does not explicitly mention when not to use it or alternatives, but the mutation context and required fields make usage clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It declares 'Read-only' and mentions the underlying GraphQL query. However, it does not cover error handling, permissions, or rate limits.

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 efficient sentences, front-loaded with the main action, and no unnecessary words. Every part adds 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?

For a simple single-fetch tool with one parameter and no output schema, the description covers the return fields (description, state, assignee, comments) and the identifier format, providing sufficient context 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 coverage is 100% with a clear parameter description. The tool description echoes this information without adding new meaning beyond the schema, so 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?

Description clearly states the action (fetch), resource (issue), and identifiers (UUID or human identifier). It distinguishes from siblings like linear_search_issues that perform searches.

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?

States 'Read-only' and implies use when you have a specific ID, but does not explicitly mention when to use alternatives like linear_search_issues. Still clear for a single-fetch tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It explicitly states 'Read-only' and mentions the GraphQL query used, providing good transparency about the tool's safety profile and expected 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?

Two sentences with no wasted words. The purpose is front-loaded, and the read-only nature and GraphQL hint are efficiently included.

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 covers the return fields (number, name, start/end dates) and mentions the GraphQL query. Given no output schema and low parameter count, this is sufficient for an agent to understand the tool's 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?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the teamKey parameter ('optionally scoped to a team by key') and the returned fields, which helps the agent understand 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 the verb 'list' and resource 'cycles', and adds detail about optional team scoping and returned fields (number, name, start/end dates). It is specific enough to distinguish from sibling tools like linear_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?

The description implies usage for listing cycles with optional team filtering, but does not explicitly state when to use this tool versus alternatives like linear_list_projects or linear_search_issues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must convey behavioral traits. States 'Read-only', which is crucial, but lacks details on pagination, rate limits, or auth requirements. Fails to fully compensate for missing 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?

Two short, front-loaded sentences convey purpose, scope, and key behavior (read-only, GraphQL). 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 simple list tool with one optional parameter and no output schema, the description covers the purpose, read-only nature, and returned fields. Lacks details on pagination behavior but is sufficient given 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?

Schema coverage is 100%, with the 'first' parameter well-described in the schema (max 250, default 50). Description adds no additional meaning or usage context for the parameter, so baseline 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?

Clearly states 'List projects' with specific verb and resource, and enumerates returned fields (id, name, state, progress, target date). Distinct from sibling tools like linear_create_issue or linear_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?

Implied read-only usage by the 'Read-only' tag, but no explicit when-to-use or when-not-to-use guidance. Alternatives not mentioned, though sibling tool names provide context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Declares 'Read-only' and mentions the underlying GraphQL query, which adds transparency. With no annotations provided, the description adequately conveys the safe, non-destructive nature. Could disclose more about rate limits or response structure, but sufficient for a simple list 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?

Three sentences with no wasted words. First sentence states purpose and return fields, second gives usage guidance, third declares read-only and underlying technology. Well-structured and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the essential aspects: return fields, read-only nature, and underlying query. Does not mention pagination behavior (though 'first' parameter handles it) or ordering, but for a simple list tool it is reasonably 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?

Schema description coverage is 100% for the single parameter 'first', so baseline is 3. The tool description does not add any extra meaning beyond what is already in the schema; it merely repeats the parameter in the context of the overall function.

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?

Clearly states 'List the teams in the workspace (id, key, name).' The verb 'list' and resource 'teams' are specific. It distinguishes from sibling tools like linear_list_cycles and linear_list_projects by focusing on teams, and also provides downstream usage hints.

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 clear context on how to use the output: team id for linear_create_issue, team key for linear_search_issues. However, it does not explicitly state when to use this tool versus alternatives 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.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description mentions 'Read-only' and the underlying GraphQL query, providing some behavioral context. However, it lacks details on authentication needs, rate limits, or response structure (e.g., fields returned, pagination). Since no annotations are provided, the description should have offered 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 extremely concise: two sentences that convey purpose, scope, and technical detail. Every clause adds value without waste.

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 optional param, no output schema), the description covers core purpose and read-only nature. However, it does not mention what fields are returned or pagination behavior. With no annotations, additional completeness would help, but it remains minimally adequate.

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 full coverage (100%) for the single parameter 'first', including a description, default, and constraints. The description adds no additional semantic value beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists issues assigned to the current user, specifying the verb 'list' and the resource 'issues assigned to the current user'. It distinguishes from sibling tools like linear_search_issues (which searches broadly) by focusing on the viewer's assigned 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 for retrieving the current user's assigned issues, but does not explicitly state when to use this tool versus alternatives (e.g., linear_search_issues for searching all issues, linear_get_issue for a specific issue). No exclusions or when-not contexts are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description labels the tool as 'Read-only', which is a key safety trait. No annotations exist, so the description carries the full burden. It does not mention other behaviors like pagination, rate limits, or error handling.

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, with two sentences that front-load the main purpose. Every sentence adds value, and there is no extraneous 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?

The description covers filtering and safety but lacks details on return format, pagination (despite a 'first' param), and error scenarios. Without an output schema, more context on results would be helpful for a search 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 the description does not need to add much. It restates filter options and adds 'matches title' for the query parameter, which aligns with the schema's 'containsIgnoreCase'. No significant new meaning is added.

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 finds and filters issues. It uses a specific verb 'find' and lists filter criteria. However, it does not explicitly distinguish itself from siblings like 'linear_get_issue' for single-issue retrieval or 'linear_my_issues' for personal 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 explicit guidance on when to use this tool versus alternatives. The description mentions filtering options but does not specify when to use this search tool over other issue-related tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.