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

No annotations are provided, so the description bears the full burden of behavioral disclosure. It only states 'Add a comment' without mentioning permissions, idempotency, reversibility, or what the response contains—significant 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 concise sentence, well-front-loaded with the core action. However, it is under-specified; the brevity leaves critical details unstated, so it's concise but not optimally structured for utility.

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

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

With no output schema, no annotations, and only partial parameter documentation, the description is inadequate for an agent to call the tool correctly. It doesn't explain return values, error conditions, or any prerequisites, making it incomplete for a mutation operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33% (parentId has a description, issueId and body do not). The description adds no parameter information at all, failing to compensate for the low coverage. It doesn't clarify the meaning of issueId, body, or the optional parentId 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 clearly states the action ('Add a comment to an issue') and the optional threaded-reply feature, which distinguishes it from sibling tools like linear_update_comment or linear_delete_comment. However, it doesn't explicitly name alternatives, so it's clear but not fully differentiated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives such as linear_update_comment or linear_list_comments. The context is implied but no explicit when/when-not conditions 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?

Annotations already provide idempotentHint=true and destructiveHint=true. The description adds the valuable context that archiving is reversible in Linear, which softens the destructive hint and clarifies the state change. It does not fully detail all effects, but it goes beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words. It front-loads the action and includes a useful qualifier about reversibility, making it efficient and scannable.

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 one-parameter tool with annotations covering idempotency and destructiveness, the description is largely complete. It adds the key reversible context and does not need to explain return values since there is no output schema. It could mention the archive state effect more explicitly, but the complexity is low.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description does not explicitly explain the 'id' parameter. However, with only one required string parameter and the tool name/description referencing 'issue', an agent can reasonably infer that 'id' is the Linear issue identifier. The description adds little beyond the schema but is not misleading.

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

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

The description uses a specific verb ('Archive') and resource ('an issue'), and the parenthetical 'reversible in Linear' distinguishes it from permanent deletion tools like linear_delete_issue. It clearly communicates what the tool does and how it differs from siblings.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: when an issue should be archived rather than permanently deleted. However, it does not explicitly name alternatives or state when not to use it, leaving the routing to inference from the sibling tool names.

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 are present, so the description carries the full behavioral burden. It only states the action and supported fields; it does not disclose side effects, return values, validation behavior, idempotency, or permission requirements, leaving significant ambiguity 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?

Two sentences with the core action front-loaded and zero fluff. The feature enumeration is compact and appropriate for the tool's scope.

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 12-parameter creation tool with no output schema and no annotations, the description is too thin. It omits behavior, return value, prerequisites, and does not clarify the parameters that lack schema descriptions, so an agent must infer critical details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 50%, so the description should compensate for undocumented parameters, but it merely lists field names (assignee, state, project, etc.) without adding meaning. The only semantic note about parentId creating a sub-issue largely duplicates the schema description for parentId.

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

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

The description opens with 'Create an issue,' a specific verb and resource, and the sibling tools include update/delete/list variants, so an agent can immediately distinguish this as the creation tool. The list of supported fields reinforces scope without ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the verb 'Create' and the tool name, but there is no explicit statement of when to use this versus siblings like linear_update_issue or linear_create_issue_relation. No prerequisites, exclusions, or fallback conditions 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?

With no annotations, the description carries the full behavioral disclosure burden. It discloses the core mutation and some relation types, but it omits important behavior: whether the relation is directional, whether both issues must already exist, what side effects occur, and what the operation returns. This is inadequate for a state-changing 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, front-loaded sentence with no filler. It loses a point because including 'subtask' as a relation type is misleading and does not match the schema-provided enum, so not every piece of information earns its place.

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

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

Given three required parameters, no output schema, and no annotations, the description is incomplete. It gives a high-level purpose but lacks parameter direction semantics, valid relation type alignment, and any indication of return values or failure conditions, making it insufficient for reliable invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it does not explain the meaning or direction of issueId versus relatedIssueId. It only mentions 'between two issues' and lists relation types, one of which is invalid against the schema. The agent still must infer the parameters from their names.

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

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

The description clearly states the action (create) and resource (issue relation) and identifies the operation as one between two issues. It is distinguishable from the list/delete siblings. However, it lists 'subtask' as an example relation type even though the input schema's enum contains 'similar' instead, which adds ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool versus linear_list_issue_relations or linear_delete_issue_relation knives. The only signal is the verb 'create', which is implied by the tool name and title rather than explained as a usage condition.

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 destructiveHint annotation already signals that this operation is destructive. The description adds no behavioral context beyond that, such as whether deletion is permanent, what permissions are needed, or what side effects occur.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no filler. The action, object, and identifier are all front-loaded and immediately actionable.

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 required parameter, a destructive annotation, and no output schema, the description is adequately complete. It could add usage guidance, but the low complexity means nothing critical is missing for invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema only defines id as a string with no description. The tool description adds meaning by specifying 'by its UUID', clarifying that the id must be the comment's UUID. This is sufficient for a single-parameter tool.

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

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

The description states a specific action ('Delete'), a specific resource ('a comment'), and the required identifier ('by its UUID'). This clearly distinguishes it from siblings like linear_update_comment, linear_add_comment, and linear_list_comments.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied: use this tool when you need to delete a comment. However, there is no explicit guidance about when not to use it or how it relates to alternatives such as linear_update_comment.

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 destructiveHint annotation already establishes that this mutates/deletes; the description adds 'permanently' to signal irreversibility. It does not disclose side effects such as deletion of associated comments or relations, or permission requirements, though the simple scope and annotation soften that gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

One sentence, front-loaded action, no filler. It is as concise as a single-parameter delete tool needs to be.

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 one-parameter delete, the core action and irreversibility are stated, and destructiveHint covers safety. However, the description omits id semantics and any guidance on choosing this over archive_issue, so it is not fully complete for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the description does not explain that id refers to a Linear issue identifier or give any format guidance. The agent must infer the meaning from the tool name and parameter name.

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

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

States the exact operation ('delete') and resource ('issue'), adding 'permanently' to distinguish from non-destructive actions like linear_archive_issue. The title and description together leave no doubt about what tool this is.

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 when-to-use, when-not-to-use, or alternatives. The word 'permanently' implies contrast with archive, but the description never says to prefer linear_archive_issue for reversible removal and provides no conditions.

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 destructiveHint annotation already covers the destructive nature, and the description adds no further behavioral context such as irreversibility, cascade effects, permissions, or impact on the linked issues. It essentially restates the delete 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?

A single sentence with no filler, front-loading the action and target resource. Every word contributes to the tool's meaning.

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 one-parameter destructive delete operation, the description, schema, and destructiveHint together provide enough to invoke the tool correctly. The only notable absence is usage guidance, which is not critical given the tool's 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?

With 0% schema description coverage, the description compensates by identifying the sole 'id' parameter as a relation UUID, which prevents confusion with issue or comment IDs. It does not explain how to obtain that UUID, but for one parameter this is meaningful semantic clarification.

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

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

The description states a specific action (delete) against a specific resource (relation) and further clarifies the target by 'relation UUID,' making it clearly distinct from siblings like linear_delete_issue and linear_delete_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?

The intended use is implied by the verb and resource, but the description gives no explicit guidance on alternatives or prerequisites, such as using linear_list_issue_relations to obtain the relation UUID before deletion.

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 annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds useful behavioral context by listing the included related data: state, assignee, parent, children, labels, and relations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, well-structured sentence that leads with the core purpose and then enumerates what is included. No filler or redundant content.

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

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

For a simple single-issue lookup with one parameter, the description fully covers what the tool does and what data it returns. The readOnlyHint covers safety, and the included fields are enumerated sufficiently given the absence of an output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents the id parameter with full coverage. The description reinforces this with a concrete identifier example, adding practical format context 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 clearly states the tool returns one issue by UUID or identifier, with a concrete example (ENG-4651). It specifies the resource and scope, distinguishing it from sibling tools like linear_search_issues or linear_list_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 the tool is for fetching a single issue when you already have its UUID or identifier. It does not explicitly state when not to use it or mention alternatives, but the context is clear enough for an agent to select it appropriately.

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

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

The readOnlyHint annotation already establishes that this is a safe read operation. The description adds useful context about the user being tied to the configured API key, but it does not mention potential errors or the response shape. This is acceptable for a simple getter but not rich 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, clear sentence with no filler. The verb and resource are front-loaded, and every word contributes to understanding the tool's purpose.

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

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

For a zero-parameter read-only tool, the description and annotations are sufficient to understand what it does and how to call it. There is no output schema, so the return value is only described as 'the Linear user,' which is clear enough for this simple identity lookup.

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, and the input schema is empty, so there is nothing for the description to explain. The zero-parameter baseline of 4 applies, and no additional parameter semantics are needed.

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

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

The description uses a specific verb ('Return') and resource ('the Linear user that owns the configured API key'), clearly distinguishing this from sibling tools like linear_list_users. The title reinforces the 'current user' concept, leaving no ambiguity about what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this is the tool to use when you need the current authenticated user, but it does not explicitly contrast it with linear_list_users or state when not to use it. For a zero-parameter identity tool, the context is adequate but not explicit about alternatives.

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 readOnlyHint=true annotation already establishes that this is a safe read operation, and the description merely echoes that by saying 'List.' It adds minimal behavioral context beyond the annotation—the per-issue scoping is conveyed, but nothing about ordering, pagination, or what is returned, despite the presence of a limit parameter suggesting paged behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with no filler, and the core action is stated upfront. It is appropriately minimal for what it covers, though the brevity edges toward under-specification rather than genuine conciseness.

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

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

For a simple read tool with readOnlyHint=true, one required parameter, and no output schema, the description is barely adequate. It identifies the resource and scope, but the limit parameter's semantics (pagination behavior) and any return-shape expectations are unaddressed. Given the low complexity, this is a minor but real gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries the burden of explaining the two parameters, but it fails to do so. 'On an issue' loosely implies issueId, yet limit is completely undocumented in both the schema (which only gives types and bounds) and the description. The description adds almost no meaning beyond the raw JSON 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 states a specific verb and resource: 'List comments on an issue.' The 'on an issue' scope distinguishes it from list tools for other resources (linear_list_issues, linear_list_teams) and from comment mutations (linear_add_comment, linear_update_comment, linear_delete_comment). It is clear but minimal, lacking any detail about the shape or filtering of the listing.

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 when-to-use or when-not-to-use guidance is provided. The description does not explain when to choose this over linear_search_issues or mention prerequisites like needing a valid issueId. Usage context is only implied by the tool's name and parameter requirement.

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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds that results can be scoped to a team, which is a behavioral nuance not in the annotation. However, it does not disclose pagination behavior, default scope when no teamId is provided, or response format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. It efficiently conveys the core action and the optional scoping behavior without wasting words.

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

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

For a simple read-only list tool with two optional parameters and no output schema, the description is largely sufficient. It covers the main action and the team filter, and the limit parameter’s default is visible in the schema. Minor gaps include the precise behavior without a teamId and the meaning of 'cycles' in Linear, but these are acceptable for a domain-savvy agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, so the description must compensate. It partially explains teamId ('optionally scoped to one team') but does not explain 'limit' at all. The schema provides type and default for limit, but the description adds no meaning beyond the raw 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 states a specific verb ('List') and resource ('cycles'), and adds a scoping qualifier ('optionally scoped to one team') that differentiates this from other list tools. It is immediately clear what the tool does and how it relates to siblings like linear_list_projects or linear_list_labels.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to choose this tool over alternatives. The description only states the basic function and the optional team filter; it does not mention any prerequisites, exclusions, or scenarios favoring another sibling 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?

The readOnlyHint annotation already establishes the safe read-only nature. The description adds only the obvious listing behavior and single-issue scope, without mentioning pagination, ordering, error behavior, or what relation types are returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. It is concise, though it is also terse enough to border on under-specification.

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

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

With no output schema, no parameter descriptions, and no relation-type context, the description is adequate only for the simplest invocation. It omits important context such as pagination behavior and how relations relate to issue lookups.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not compensate: it never mentions issueId, limit, their defaults, or their role in the call. All parameter meaning is left to the raw schema, which only gives types and constraints.

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

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

The description uses a specific verb 'List' with resource 'relations' and a clear scope 'for one issue.' This distinguishes it from sibling mutation tools like create_issue_relation and delete_issue_relation, though it doesn't elaborate on what relations will be shown.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no guidance on when to use this tool versus alternatives such as get_issue or create_issue_relation. No exclusions or selection criteria are provided, so the agent must infer usage solely from the tool name.

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

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

The annotations include readOnlyHint=true, which covers the read-only nature, so the description doesn't need to restate that. However, it does not disclose other behaviors such as default limit (20), max limit (100), or that includeArchived defaults to false, which are important for setting expectations. It also does not describe the return format (e.g., list of issue objects), but given the readOnlyHint and no output schema, a bit more behavioral context (e.g., pagination) would be useful. The description doesn't contradict the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficient: two sentences that pack key usage details without fluff. It front-loads the core function (list issues with filters) and then provides targeted guidance on special values. It could be slightly more structured (e.g., bullet points), but it's concise enough and every sentence 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?

With 10 parameters, no required params, and no output schema, the description covers the key decision points (filters and special values) but leaves gaps. It doesn't mention default limit, pagination, or what the response looks like. Given the complexity (many filters), the description should explain how filters combine (AND vs OR) and the precedence of state vs stateType. It's adequate for basic use but not complete for advanced filtering scenarios.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 30% (3 out of 10 parameters have descriptions: limit, state, assigneeId). The description adds semantics for assigneeId ('me' special value) and state vs stateType, which goes beyond the schema. However, it does not explain the relationship among stateId, state, stateType, or that stateType is an enum. While the description helps for the most ambiguous parameters, it doesn't fully compensate for the 70% of parameters with no description (e.g., teamId, projectId, cycleId are clear by name, but labelId/stateId are less so).

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

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

The description clearly states the tool's purpose: 'List issues with optional ... filters.' It uses a specific verb ('list') and resource ('issues'), and enumerates the filter dimensions (team, project, cycle, assignee, state, label), which distinguishes it from siblings like linear_get_issue (single issue) or linear_search_issues (text-based search).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance, including how to use special values: 'Pass assigneeId='me' for the current user' and 'pass state for an exact state name such as 'In Review', or stateType for backlog|unstarted|started|completed|canceled.' This helps the agent choose between state and stateType, which is crucial given both parameters exist. It also implies when to use this tool vs. linear_search_issues (for structured filtering rather than text search).

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?

Annotations already declare readOnlyHint=true, so the description need not restate safety. It adds the behavioral nuance of optional team scoping, which is useful. But it does not mention pagination behavior, the effect of the limit parameter, or what happens when teamId is omitted. This is adequate given the read-only annotation, but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the core action and resource, then adds the optional scoping detail. There is no filler or redundant text, and every word earns its place.

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

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

For a low-complexity read-only tool with two optional parameters and no output schema, the description covers the essential behavior: listing labels and optional team scoping. The schema documents limit's constraints, so the only minor gap is not explicitly stating that omitting teamId returns all labels, though that is logically implied.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains teamId's role ('scoped to one team') but says nothing about limit, leaving the agent to infer its meaning from the name and schema constraints. The description only partially clarifies the two parameters.

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

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

The description clearly states the tool lists issue labels, with an optional team scope. This identifies a distinct resource type among sibling list tools, but it does not explicitly name or differentiate from siblings like linear_list_workflow_states. The verb 'List' and resource 'issue labels' are specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'optionally scoped to one team' implies a usage condition: use teamId when you need labels for a specific team. However, it provides no explicit guidance on when to prefer this tool over alternatives, nor any exclusions or prerequisites. The usage is implied rather than stated.

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

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

Annotations declare readOnlyHint=true, so the safety profile is already known. The description adds useful scoping behavior, but it does not disclose return format, pagination, or how teamId and includeArchived affect results.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with the verb and scope front-loaded and no filler. Every word earns its place.

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

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

For a simple read-only list tool, the core behavior and scope are covered. However, with no output schema and no parameter explanations, an agent must infer return shape and filtering semantics, leaving clear gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, and the description does not mention any of the three parameters (limit, teamId, includeArchived). It adds no meaning beyond the schema's bare property names and defaults.

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

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

The description uses a specific verb ('List') and resource ('issues'), and precisely scopes the result to 'assigned to the API key's own Linear user.' This clearly distinguishes it from sibling tools like linear_list_issues 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 provides no explicit when-to-use guidance or alternatives. The only usage context is implied by the phrase 'own Linear user'; an agent cannot tell from the description when to choose this over linear_list_issues 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?

The readOnlyHint annotation already covers the read-only safety profile, and the description adds the optional team-scoping behavior. However, it does not disclose pagination behavior, default limit, or what the response contains, though annotations lower the burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no filler. It conveys the core operation and the key optional parameter in a compact form, earning each word.

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

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

For a simple read-only list tool with no required parameters, the description is largely sufficient. It could mention that teamId references a Linear team ID or that results return project objects, but the low complexity and readOnlyHint reduce the need for extensive context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, but it only vaguely references team scoping. It does not explain the 'limit' parameter, its default of 50, or the maximum of 100, leaving one parameter semantically undocumented.

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

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

The description clearly states the action ('List') and resource ('projects'), with an optional team scope. It is immediately distinguishable from sibling list tools that operate on different resources such as teams, users, cycles, and 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 does not explain when to use this tool versus alternatives, nor does it mention exclusions or prerequisites. The only usage hint is 'optionally scoped to one team,' which is more of a parameter-level note than guidance about tool selection.

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?

Annotations already declare readOnlyHint=true, so the read-only nature is covered. The description adds the visibility scope (only teams visible to the API key), which is useful behavioral context, but does not disclose other traits like pagination behavior or ordering. With annotations carrying the safety profile, a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no wasted words. The verb and resource lead immediately, and the scope qualifier adds necessary nuance without clutter.

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

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

For a simple read-only list tool with one optional parameter and no output schema, the description correctly captures the core function and scope. It could be slightly more complete by noting that `limit` caps the number of returned teams, but the tool's low complexity makes this a minor omission.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one parameter (`limit`) with 0% description coverage, so the description should compensate by explaining its meaning or usage. It does not mention `limit` at all, leaving the agent to rely on the parameter name and schema constraints. This is a clear gap in parameter documentation.

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

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

States a specific verb ('List') and resource ('teams') with an important scope qualifier ('visible to the API key'). This clearly distinguishes it from sibling list tools like linear_list_users or linear_list_projects, so an agent can immediately identify its target resource.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used when an agent needs the teams accessible to the current API key. It does not explicitly name alternatives or provide when-not-to-use guidance, but the resource is distinct from all siblings, making the intended context 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?

The readOnlyHint annotation already covers the safety profile, and the description adds that results can be filtered by name, display name, or email. It does not disclose pagination, ordering, or rate-limit behavior, but for a simple read-only list this is acceptable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The entire description is a single, front-loaded sentence with no filler. It states the primary action first and then adds optional filter behavior, earning its place.

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

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

For a simple read-only list with optional filter and limit parameters, the description plus schema and annotations cover the essential information. It does not describe return structure, but no output schema exists and the result of listing users is evident.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description compensates by explaining that the query parameter matches name, display name, or email. The limit parameter is adequately specified by its name, schema type, default, minimum, and maximum.

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

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

The description uses a specific verb (List) and resource (users), and adds filter semantics (name, display name, email) that make the tool's function concrete. This distinguishes it from sibling tools like linear_get_viewer and the other list_* tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'List users, optionally filtered...' gives clear context for when to invoke the tool, and the sibling toolset makes comparison straightforward. It does not explicitly list exclusions or alternatives, but the purpose is unambiguous.

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 readOnlyHint annotation already covers the safety profile, and the description adds value by listing the expected state values. However, it does not disclose behavior around pagination, filtering, or whether an omitted teamId changes results, so it only partially supplements the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence with the action and key scope front-loaded. The parenthetical state list is useful without adding bloat, though additional parameter context would be welcome.

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

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

For a simple read-only listing tool with no required parameters, the description is fairly adequate. Still, the missing parameter semantics and lack of any output-shape hints leave an agent needing to infer important details about how to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain parameter meaning. It loosely connects teamId via 'for a team' but says nothing about limit and fails to clarify whether teamId is optional or required.

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

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

The description clearly states the tool's action ('List') and resource ('workflow states') and usefully enumerates the kinds of states returned. It is distinct enough from sibling tools like linear_list_teams or linear_list_projects, though it does not explicitly call out 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?

The description provides no guidance on when to use this tool versus alternatives, nor does it explain whether teamId is required or what happens if it is omitted. The phrase 'for a team' implies a usage condition, but it is not made explicit.

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 readOnlyHint annotation already covers safety, and the description adds that matching is by title, description, or identifier and that filters are supported. However, it does not disclose behavior like partial vs. exact matching, archived-issue handling, or result limits beyond the schema defaults.

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 compact sentences with no filler; the core action and search scope are front-loaded, and the filter list is summarized efficiently. Every phrase earns its place.

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

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

The core search and filter capabilities are covered, but with no output schema and siblings for listing/getting issues, the agent still lacks guidance on return shape and when to choose this tool over linear_list_issues or linear_get_issue. includeArchived and limit behavior are also left to the schema defaults.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description maps five of the eight parameters (team, assignee, state, project, label) and clarifies that query can be text or an identifier. However, limit and includeArchived remain undocumented in both the schema and the description, and with only 38% schema coverage the description only partially compensates.

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

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

The description states a specific verb ('Search') and resource ('issues'), and adds the searchable fields: title, description, or identifier. It is clearly distinct from list/get siblings by its text-search focus, but it does not explicitly name an alternative for exact-identifier retrieval, so it falls just short of full differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for finding issues by free text or identifier and for filtering by team/assignee/state/project/label, but it gives no explicit when-to-use vs. when-not-to-use guidance. With siblings like linear_list_issues and linear_get_issue available, the absence of routing guidance is a gap.

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 are provided, so the description carries the full burden of behavioral disclosure. It states the operation is an update, implying mutation, but does not disclose whether the update is partial or full replacement, whether the body must be non-empty, whether the comment must belong to the caller, or what the response contains. For a mutation tool with zero annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that front-loads the action and object. It earns its place with no wasted words, but it is so brief that it sacrifices useful context. Still, for what it attempts to convey, it is well-structured.

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

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

Given the tool has no annotations, no output schema, and 0% schema description coverage, the description is too thin to be complete. An agent knows the tool updates a comment body by UUID, but lacks information about required permissions, idempotency, response format, or constraints on the body. Sibling tools like linear_add_comment and linear_delete_comment exist, so usage boundaries should be clarified.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for the schema's lack of parameter documentation. The description only clarifies that 'id' is a UUID, but it does not explain what 'body' should contain (e.g., plain text vs. markdown, length limits) or whether 'id' refers to the comment UUID specifically. With two required parameters and no schema descriptions, this is insufficient.

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

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

The description states a specific verb ('Update') and resource ('a comment body') and identifies the identifier type ('by its UUID'). It is clear what the tool does, though it does not explicitly distinguish it from sibling tools like linear_add_comment or linear_delete_comment. The title reinforces the same message without adding new differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided about when to use this tool versus alternatives. The description does not mention that this tool is for editing an existing comment, while linear_add_comment is for creating one, or linear_delete_comment for removing one. An agent must infer usage from the tool name and sibling list.

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 behavioral disclosure burden. It mentions that parentId moves/reparents the issue, but it does not disclose other side effects like state transitions triggering workflows, whether updates are partial or full, permission requirements, or reversibility.

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 states the core purpose and enumerates the key fields without filler. Every phrase adds useful information and no redundant wording is present.

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

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

Given 12 parameters, no annotations, and no output schema, the description is too sparse. It does not explain the return value, error behavior, whether labelIds replaces or appends, or whether changes are atomic, which an agent needs for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33%, so the description must compensate for undocumented parameters. It adds high-level meaning by grouping fields (e.g., state, assignee, labels, cycle) and clarifying parentId as reparenting, but it does not provide formats, allowed values, or dependency relationships beyond what the schema already gives.

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

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

The description uses a specific verb and resource ('Update a Linear issue') and lists the exact mutable fields, including subtle ones like parentId for reparenting. It clearly distinguishes this tool from siblings like linear_create_issue, linear_get_issue, linear_archive_issue, and linear_delete_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?

The description implies this is the tool for modifying an existing issue, but it gives no explicit when-to-use guidance or alternatives. It does not clarify when to prefer create_issue, delete_issue, or archive_issue, and it doesn't state prerequisites such as the issue needing to exist.

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