Server Quality Checklist

Tool Scores

• add_commentA
  3.7/5.0
  Behavior2/5

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

  There are no annotations, so the description carries the full burden of behavioral disclosure. It reveals that Markdown is supported and that an identifier is needed, but does not mention side effects, permissions, reversibility, or what happens on success or failure. For a mutation tool, this is a notable gap.

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

  Conciseness5/5

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

  The description is extremely concise and front-loaded. The primary action appears in the first sentence, followed by Markdown support and identifier guidance. Every sentence earns its place with no redundant information.

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

  Completeness3/5

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

  The description provides enough for a basic call: identifier format and the action are clear. However, with no output schema, it does not explain the return value or any error conditions. For a simple write operation this is minimally adequate but still incomplete.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. It meaningfully defines 'identifier' as a human issue identifier with an example, and notes that Markdown is supported for the body. However, 'body' itself is not explicitly described as the comment text, though it is inferable.

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

  Purpose5/5

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

  The description begins with a specific verb and resource: 'Post a comment on a Linear issue.' This clearly distinguishes it from siblings like get_comments, create_issue, and update_issue. The tool's action is unambiguous.

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

  Usage Guidelines4/5

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

  The description clearly implies when to use the tool: when a comment needs to be added to an existing Linear issue. It does not explicitly exclude alternatives or state when not to use it, but the action is distinct enough among siblings that the usage context is clear.

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

• search_issuesA
  3.9/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the burden of behavioral disclosure. It does well by explaining that invalid names return an error listing valid options rather than an empty result, and that state resolution depends on whether a team is supplied. This helps an agent anticipate failure modes beyond what the schema shows.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose and then provides compact, example-rich parameter guidance. Every sentence adds value, with no fluff or repetition, making it appropriately sized for the amount of behavioral detail it needs to convey.

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

  Completeness4/5

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

  Given there are no annotations and no schema descriptions, the description covers the most critical contextual ground: filter formats, name resolution, and error semantics. It does not mention pagination or alternative tools, and it could be slightly stronger on when to use search versus direct issue lookup, but the presence of an output schema reduces the need for return-value detail.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate. It gives concrete formats and examples for team, state, and assignee, and clarifies the state-matching behavior. Query and limit get less attention, but the query's role is clear from 'full-text search' and limit is self-explanatory from the schema.

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

  Purpose4/5

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

  The description clearly states it performs 'Full-text search over Linear issues, with optional filters,' naming both the operation and the resource. It does not explicitly differentiate itself from sibling tools like get_issue or list_my_issues, but the full-text search semantics makes the distinction mostly inferable.

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

  Usage Guidelines3/5

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

  The description provides practical guidance for populating filters, such as team key/name formats, state resolution behavior, and using list_users for assignees. However, it never explicitly says when to prefer this tool over alternatives like get_issue or list_my_issues, nor does it state 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.

• list_teamsA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden. It clearly discloses that the tool returns a collection of {key, name} pairs and explains the semantic meaning of team keys. As a simple list operation, this is sufficient, though it omits caveats like 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.

  Conciseness5/5

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

  Two tight sentences with no wasted words. The core action and output format are front-loaded, and the illustrative GOV-123 example makes the key-prefix concept immediately understandable.

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

  Completeness5/5

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

  For a zero-parameter, read-only list tool with an output schema, the description fully covers what an agent needs to know, including the practical meaning of the returned data. No meaningful gaps remain.

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

  Parameters4/5

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

  The tool has zero parameters, so there is nothing for the description to add beyond the schema. The baseline of 4 applies because no parameter documentation is needed.

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

  Purpose5/5

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

  States a specific verb and resource ('List Linear teams') and defines the output shape as {key, name}. The explanation of team keys as the prefix of issue identifiers (e.g., GOV in GOV-123) further clarifies the tool's purpose and distinguishes it from other list_* siblings.

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

  Usage Guidelines3/5

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

  The description implies when to use this tool: when you need team keys to understand or construct issue identifiers. However, it does not explicitly name alternatives or state when not to use it, leaving the routing decision to inference.

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

• get_commentsA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the burden of behavioral disclosure. 'Fetch' conveys a read-only operation, and 'oldest first' provides meaningful ordering behavior. It does not mention auth or pagination, but the output schema covers the return shape.

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

  Conciseness5/5

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

  Two tight sentences with no filler. The core action and ordering are front-loaded, followed by the parameter clarification. Every word earns its place.

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

  Completeness4/5

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

  For a single-parameter read tool with an output schema, the description is nearly complete: it gives the resource, ordering, and identifier format. The only minor gap is the absence of explicit guidance on when to choose this over sibling tools, but nothing essential to calling it correctly is missing.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate. The line 'identifier: human issue identifier, e.g. GOV-123' adds crucial semantic meaning and an example that the raw schema lacks. It fully clarifies the only parameter without being verbose.

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

  Purpose5/5

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

  The description states a specific action ('Fetch'), a precise resource ('comments on a Linear issue'), and a useful ordering detail ('oldest first'). This clearly distinguishes it from siblings like get_issue, add_comment, and list_my_issues.

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

  Usage Guidelines4/5

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

  The intended use case is clear: when you need an issue's comments, oldest first. It does not explicitly name alternatives or exclusions, but the read-only comment-fetching context is unambiguous enough to guide tool selection.

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

• list_statesA
  4.5/5.0
  Behavior4/5

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

  There are no annotations, so the description carries the behavioral burden. It discloses the return shape ({name, type}), that states are in workflow order, and that these values are accepted by create_issue and update_issue. It does not cover error behavior, but this is adequate for a simple read-only list tool.

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

  Conciseness5/5

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

  Three short sentences, each earning its place: what is returned, why it matters, and how to specify the parameter. The most important information is front-loaded.

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

  Completeness5/5

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

  For a single-parameter list tool with an output schema present, the description is complete. It covers the parameter semantics and the relationship to other tools without unnecessary detail.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must explain the parameter. It does: 'team: team key or full team name.' This adds meaningful guidance beyond the schema's bare 'Team' string property.

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

  Purpose5/5

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

  The description clearly states the verb 'List' and the resource 'workflow states for a team', plus output format and ordering. It is immediately distinguishable from sibling list tools like list_labels and list_users by naming the specific resource type.

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

  Usage Guidelines4/5

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

  The description explicitly connects states to create_issue and update_issue, telling the agent this is the source for valid `state` values. It does not explicitly say when not to use alternatives, but the usage context is clear enough.

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

• list_usersA
  4.5/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral disclosure burden. It discloses that only active users are returned, that the query filter is optional and case-insensitive, and that it searches over both name and email. It does not discuss pagination or rate limits, but for a simple read-only list tool the provided behavior is sufficient.

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

  Conciseness5/5

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

  The description is two efficient sentences: the first states the core purpose, and the second adds the assignee integration and the query semantics. There is no filler or redundant repetition of schema details.

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

  Completeness5/5

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

  For a simple list tool with one optional parameter and an output schema, the description is complete. It explains the scope, the filter behavior, and how the results relate to other tools, so an agent has enough context to call it correctly.

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

  Parameters4/5

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

  The input schema provides only the type and default for `query` with 0% description coverage. The description compensates by defining it as an optional, case-insensitive substring filter over name and email, which is exactly the semantic detail needed to use the parameter properly.

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

  Purpose5/5

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

  The description starts with a clear verb and resource: 'List active Linear users.' It also specifies the output shape as {name, email}, and identifies the specific role of `name` for create_issue/update_issue, which distinguishes it from the other list tools like list_teams or list_labels.

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

  Usage Guidelines4/5

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

  The description gives a concrete usage context: the returned `name` field is the display name accepted by create_issue and update_issue for `assignee`. It does not explicitly state when not to use this tool, but the practical connection to the issue-editing tools gives clear guidance.

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

• create_issueA
  4.6/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the behavioral burden. It states the mutation ('Create') and the return behavior ('Returns the created issue including its new identifier'), which is valuable. It does not discuss failure modes, permissions, or side effects, but the core behavior is transparent enough for an agent to know what invoking it will do.

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

  Conciseness5/5

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

  The description is compact and front-loads the purpose and return value, then uses a clean parameter-by-parameter list. Every line adds information beyond the schema rather than repeating it.

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

  Completeness5/5

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

  For a 7-parameter create operation with no annotations and no output schema, the description covers the action, the return value, and the semantics of all non-obvious parameters, and tells the agent which sibling tools to use for valid values. This is sufficient for correct selection and invocation.

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

  Parameters5/5

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

  Schema description coverage is 0%, so the description must explain parameters on its own. It does so for team, assignee, state, priority, and labels, including formats, examples, and references to sibling tools for valid values. The remaining params, title and description, are self-evident from their names and schema.

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

  Purpose5/5

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

  The description opens with 'Create a Linear issue', a specific verb and resource, and adds what is returned. This clearly distinguishes it from sibling tools like update_issue or get_issue.

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

  Usage Guidelines4/5

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

  It gives clear context for when to use the tool: to create a new Linear issue. It also points to list_users, list_states, and list_labels as lookup mechanisms for valid assignee, state, and label values. It does not explicitly say when not to use it versus update_issue, but the verb 'Create' makes this largely inferable.

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

• get_issueA
  4.6/5.0
  Behavior4/5

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

  With no annotations available, the description carries the behavioral disclosure burden. 'Fetch' clearly signals a read operation, and the description transparently lists the exact fields returned, including the git branch name Linear suggests. It does not cover error behavior or authentication, but for a simple get-by-identifier tool this is reasonably transparent.

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

  Conciseness5/5

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

  Two sentences with no filler. The purpose is front-loaded, the identifier format is immediately clarified, and the return-value enumeration is useful and compact.

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

  Completeness5/5

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

  For a single-parameter fetch tool with no output schema, the description is complete: it explains how to identify the issue, what data will be returned, and implies a read-only operation. Nothing essential for selecting or invoking the tool is missing.

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

  Parameters5/5

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

  Schema description coverage is 0%, yet the description fully compensates by explaining that the sole parameter is a human identifier and providing a concrete format example ('GOV-123'). This adds meaning beyond the bare schema field name 'identifier'.

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

  Purpose5/5

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

  The description uses a specific verb ('Fetch'), identifies the resource ('a Linear issue'), and specifies the lookup mechanism ('by its human identifier') with a concrete example ('GOV-123'). This clearly distinguishes it from sibling tools like search_issues.

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

  Usage Guidelines4/5

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

  The description makes it clear this tool is for fetching an issue when its human identifier is already known. It does not explicitly mention alternatives such as search_issues when the identifier is unknown, but the context strongly implies the appropriate use case.

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

• list_labelsA
  4.6/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and does well: it discloses the optional-team behavior, the ordering of team labels before workspace-wide labels, and the difference between with/without team. It stops short of covering error/auth/pagination behavior, but these are minor for this 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.

  Conciseness5/5

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

  Three compact sentences: the primary purpose is first, followed by the parameter behavior, then the integration point with create/update tools. No filler or repetition.

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

  Completeness5/5

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

  For a single-optional-parameter list tool with a known output schema, the description covers the operation, the parameter effect, the return shape, and the downstream consumers. Nothing essential for selecting and invoking the tool is missing.

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

  Parameters5/5

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

  The schema provides only a nullable Team string with a default; the description explains that team may be a key or full name and precisely how it changes the returned set. This fully compensates for the 0% schema description coverage.

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

  Purpose5/5

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

  States a specific action ('List'), resource ('issue labels'), and scope ('that can be applied to an issue'). The example format and team behavior make it distinct from sibling list tools such as list_teams, list_states, and list_users.

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

  Usage Guidelines4/5

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

  The description clearly primes usage by noting that the returned names are what create_issue and update_issue accept for labels, so an agent knows to call it before those tools. It does not explicitly name siblings as alternatives or state when not to use it, but the context is clear.

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

• list_my_issuesA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the disclosure burden and does well: it reveals result ordering, that state filtering happens after fetch, the over-fetch multiplier, the best-effort window, and the 'raise limit' remedy. This goes well beyond the basic 'list' semantics.

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

  Conciseness5/5

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

  The description is front-loaded with the core purpose and then cleanly documents each parameter. The longer state caveat earns its space because the best-effort behavior is non-obvious and actionable.

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

  Completeness5/5

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

  Together with the supplied output schema and defaults, the description gives everything needed to call the tool correctly: scope, ordering, parameter semantics, and a performance caveat. There is no missing safety or behavior context given the read-only nature of the operation.

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

  Parameters5/5

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

  Schema description coverage is 0%, but the description fully compensates for both parameters. state gets a type of value, case-insensitivity, post-fetch behavior, and caveats; limit is defined as the maximum count returned.

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

  Purpose5/5

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

  The opening sentence names a specific verb and resource: listing issues assigned to the API key owner, ordered by most recent update. This clearly distinguishes it from sibling tools like search_issues (general search) and get_issue (single issue).

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

  Usage Guidelines3/5

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

  The description makes the tool's context clear: use for owner-assigned issues with optional state filtering. However, it never states when not to use it or points to alternatives such as search_issues for broader queries, so selection guidance is only implied.

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

• update_issueA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description carries full behavioral weight and does so well: it discloses partial-update semantics, the destructive label-replacement behavior, name resolution against the issue's team, and the priority scale. This goes well beyond the schema and tells an agent exactly what side effects to expect.

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

  Conciseness5/5

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

  The description is compact, front-loaded with the core behavior, and uses a clear bullet-like structure for field semantics. Every sentence adds information; there is no repetition of schema or filler.

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

  Completeness4/5

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

  For a 7-parameter mutation without annotations or an output schema, it covers the essential invocation semantics well: which fields are updateable, how values are resolved, and the destructive label behavior. It could additionally state the return value or null-clear semantics, but these are not blocking for correct use.

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

  Parameters5/5

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

  Schema description coverage is 0%, and the description compensates thoroughly: it explains the identifier format, the resolution rules for state/assignee/labels, the exact priority mapping, and the labels replacement behavior. Even without documentation on title/description, their meaning is self-evident from names and the update purpose.

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

  Purpose5/5

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

  The description opens with 'Update fields on an existing Linear issue', a specific verb+resource that distinguishes this from sibling create_issue (new issue) and read-only tools. The qualifier 'existing' plus the identifier field makes the tool's job unmistakable.

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

  Usage Guidelines4/5

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

  It clearly frames the tool for modifying an existing issue rather than creating one, and clarifies that only passed fields change, which is the core usage rule. It does not explicitly name an alternative or state when not to use it, but the contrast with create_issue is implied by 'existing'.

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