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

No annotations are provided, so the description carries the full burden. It discloses Markdown support and that the issue must already exist, but it does not mention permissions, side effects (e.g., notifications), or error behavior. This is modest disclosure but not comprehensive.

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: the first states the core purpose, the second provides two concrete examples. No wasted words, front-loaded, and each sentence earns its place by aiding the agent in understanding what the tool does and how to invoke it.

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 two-parameter tool with no annotations or output schema, the description covers the essential purpose, Markdown support, and expected input. It does not explain return values or error handling, but the simplicity of the tool makes this omission acceptable, though not ideal.

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

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

Schema description coverage is 100% for both parameters, and the schema descriptions already explain 'body' (including Markdown support) and 'issueId'. The description does not add significant extra parameter semantics beyond what the schema provides, so baseline 3 is appropriate.

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

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

Clearly states the action ('Add a comment'), the target ('an existing issue in Linear'), and the scope. It differentiates from siblings like create_issue and update_issue by focusing specifically on comments. The examples provide natural language patterns for invocation.

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

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

Provides clear context: use this to comment on an existing issue. It does not explicitly list alternatives or exclusions, but the phrasing 'existing issue' implies it is not for creating or updating issues. The examples further clarify appropriate usage.

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. It conveys 'full customization' and includes a useful tip about assigneeId='me', but it omits details about side effects, required prerequisites like teamId, or the creation process being immediate. There is a gap in behavioral context.

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

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

The description is concise: one clear sentence plus three illustrative examples. It is front-loaded with the core purpose and contains no redundant text. Every part 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 description gives a solid overview but could be more complete given no annotations and no output schema. It does not mention prerequisites like using get_teams for teamId (though the schema does) or what the response looks like. However, the examples and 'full customization' cover much of the context.

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

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

The schema covers all 5 parameters with 100% description coverage, so the description adds minimal extra value. The examples map to parameters ('high-priority' to priority, 'assign to me' to assigneeId), but this does not go beyond what the schema already documents.

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

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

The description clearly states the action 'Create a new issue in Linear' with a specific verb and resource, and differentiates it from sibling tools like update_issue and get_issue. The examples further clarify the intended use cases.

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

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

The description provides clear context through examples (bug report, feature request, task) but does not explicitly contrast with alternatives like update_issue or state when not to use it. It leaves room for inference rather than giving explicit exclusions.

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 burden of behavioral disclosure. It only says 'detailed information' and does not mention error behavior, permissions, response format, or what happens if the issue is not found. The examples also mislead by suggesting the ID is a human-readable key, contradicting the schema's note about UUIDs, which could cause failures.

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 short and front-loaded with a clear purpose, but the examples are wasted space and misleading. A concise description should not contain counterproductive example values that conflict with the schema.

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 single-parameter getter with no output schema, the description should cover error handling, authentication/prerequisites, and return value expectations. It does none of this, and the misleading ID examples create a significant completeness gap. The schema partially compensates, but the description still falls short.

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

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

The input schema fully covers the issueId parameter, describing it as an internal UUID and explicitly noting it is NOT a key like 'ENG-123'. However, the tool description adds no useful parameter semantics and instead uses the exact wrong format in its examples, actively misguiding the agent. This fails to add value and creates contradiction.

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

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

The description clearly states the tool retrieves detailed information about a specific issue by its ID, distinguishing it from sibling tools like search_issues or update_issue. However, the examples use human-readable keys like 'ENG-123' while the schema clarifies the parameter expects an internal UUID, slightly muddying the resource identity.

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

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

No explicit guidance is provided on when to use this tool vs alternatives. It implies usage for a specific issue ID but does not mention that search_issues is for finding issues by criteria or that get_my_issues returns issues for the current user. There is no when-not-to-use information.

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 burden of behavioral disclosure. It states the read-only scope ('all issues assigned to you') which implies safety, but it does not disclose pagination, ordering, or response behavior for empty results. This is a minimal disclosure, yielding a score of 3.

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

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

The description is concise and front-loaded with the core action, followed by relevant use cases and examples. Every sentence adds value, and it is appropriately sized for the tool's simplicity.

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

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

This is a simple tool with one optional parameter and no output schema. The description provides clear purpose, usage context, and examples. It could be more complete by hinting at the return format (e.g., a list of issues) but is adequate for the tool's complexity.

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

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

The single parameter 'limit' is fully described in the schema with a clear explanation and default/max values. The description itself adds no additional meaning to the parameter. Since schema coverage is 100%, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get all issues assigned to you in Linear.' This uses a specific verb and resource, and distinguishes it from siblings like search_issues (searching) and get_issue (single issue). The examples further reinforce the purpose.

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

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

The description provides clear usage context: 'Perfect for daily standup prep or checking your current workload.' It implies when to use this tool but does not explicitly mention exclusions or alternatives such as search_issues for broader queries, preventing a 5.

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 burden of explaining behavior. It implies a read-only list operation ('Get all teams'), but does not disclose output format, pagination, or whether archived teams are included. The behavioral information is minimal and could be more transparent.

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

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

The description is concise and well-structured: a direct statement of function, a practical use case, and an example. Every sentence contributes value without unnecessary verbosity.

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

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

For a simple zero-parameter list tool, the description covers the essential purpose and usage. However, since there is no output schema or annotations, it leaves a few gaps such as return format and team visibility, but these are minor for a straightforward list endpoint.

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

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

The tool has zero parameters, so the baseline of 4 applies. The description adds no parameter-specific details, but none are needed since there are no inputs.

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

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

The description clearly states the tool retrieves all teams in the user's Linear workspace. It distinguishes itself from sibling tools by focusing on the team resource, and the example provides a concrete natural-language trigger.

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

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

The description explicitly states when to use this tool: 'find team IDs for creating issues or filtering searches.' This gives clear context, though it does not mention exclusions or alternatives because no sibling tool handles teams.

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 burden. It states the tool retrieves all workflow states for a team, implying a read-only operation. However, it does not mention the return format, any filtering limitations, or whether archived states are included. This is adequate but lacks depth.

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

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

The description is concise and front-loaded with the core function, followed by a usage note and practical examples. Every sentence adds value, with no redundancy or fluff.

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

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

For a simple one-parameter read tool with no output schema, the description provides adequate context: what it does, why to use it, and example queries. It does not describe the response structure, but the note about finding state IDs implies the response contains IDs. This is complete enough for 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?

The input schema already documents teamId fully, including how to find team IDs via get_teams. The description adds only the phrase 'for a specific team,' which is already implied by the parameter. With 100% schema coverage, the baseline of 3 is appropriate.

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

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

The description clearly states the tool's function: 'Get all workflow states (statuses) for a specific team.' It specifies the resource (workflow states) and the scope (specific team), and distinguishes itself by noting its use case 'to find state IDs when updating issues', which differentiates it from sibling tools like update_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 provides explicit guidance on when to use the tool: 'Use this to find state IDs when updating issues.' It gives clear context and examples but does not explicitly mention when not to use it or name alternatives. Since the siblings do not include another workflow-state lookup tool, this is sufficient.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It indicates the tool checks connection and auth status but does not describe what happens on failure, whether it makes network calls, or what the return format looks like. This is adequate for a simple health check but lacks depth.

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

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

The description is two compact sentences plus a short example. It is front-loaded with the core action and resource, and every sentence adds value. No wasted words or redundant information.

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

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

Given the tool's extreme simplicity (no params, no output schema), the description covers the essential context: what it verifies and when to use it. It does not describe the response format, but for a health check, the purpose and usage are sufficiently complete.

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

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

The tool has zero parameters, and the schema coverage is 100% vacuously. As per guidelines, the baseline for zero parameters is 4. The description does not need to add parameter meaning since there are none, and it appropriately focuses on the tool's purpose.

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 ('Verify') and resource ('Linear API connection') and clearly states the additional check of authentication status. It is easily distinguished from sibling tools like search_issues and create_issue, which operate on domain data rather than connection health.

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

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

The description explicitly states 'Use this to troubleshoot connection issues' and gives a natural language example. It does not mention when not to use or alternative tools, but the when-to-use guidance is clear enough for a health check utility.

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

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

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions 'powerful filtering options' and gives examples, but it does not describe what fields are returned, pagination, sorting, or any limitations. Since there is no output schema, the agent is left without crucial information about the tool's behavior beyond the act of searching.

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 brief and front-loaded with the action, followed by three relevant examples. Every sentence earns its place; there is no filler or redundancy. It is a model of concise, informative writing.

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

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

The tool has moderate complexity (5 parameters) and full schema coverage, but lacks an output schema and annotations. The description provides examples but does not explain the response format or any important behavioral details (e.g., whether results are paginated, how limit works). It is adequate for basic use but leaves gaps that could affect correct invocation.

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

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

The input schema covers 100% of the parameters with descriptions, so the baseline is 3. The description's examples add some context for how the query parameter can be used (natural language queries), but it does not provide additional meaning for the other parameters beyond what the schema already states. The schema itself is sufficiently descriptive, including the 'me' tip for assigneeId.

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

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

The description clearly states the tool's function: 'Search for issues in Linear with powerful filtering options.' This uses a specific verb (search) and resource (issues in Linear). It is distinguishable from siblings like get_issue (retrieve a single issue) and get_my_issues (list current user's issues), though it doesn't explicitly differentiate itself from those 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 examples provide concrete usage scenarios ('Find all high-priority bugs assigned to me', 'Show open issues in the Engineering team') that imply when to use this tool. However, it does not explicitly state when to use this versus sibling tools like get_my_issues or get_issue, nor does it mention any exclusions or prerequisites.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals that the tool mutates an existing issue but gives no additional context: no mention of partial update semantics, persistence/irreversibility, required permissions, or response behavior. It also does not note that unspecified fields remain unchanged, which is a key behavioral trait for an update operation. The only implied behavior is that it modifies the issue, which is already evident from the tool name.

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

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

The description is a single, front-loaded sentence that states the purpose and lists key fields, followed by three succinct, high-signal examples. Every element earns its place; there is no fluff or repetition of schema details. The structure is easy to parse quickly, making it ideal for AI consumption.

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 6 parameters, 1 required, and no output schema, the description sufficiently covers the core usage but has minor gaps. It does not mention that only provided fields are updated (partial update), nor does it describe the return value or error behavior. However, the schema supplies parameter details, and the examples provide enough context for typical use cases. The sibling tools like get_issue and create_issue are implicitly differentiated by 'existing issue', so overall it is reasonably complete for a tool of this complexity.

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

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

The input schema covers all parameters with 100% description coverage, so the baseline is 3. The tool description adds value through its examples: 'Update issue ENG-123 to high priority' maps to priority and issueId, 'Assign issue ENG-456 to me' illustrates the special assigneeId value 'me', and 'Change the description of issue ENG-789' demonstrates description usage. These examples reinforce parameter semantics beyond the schema definitions, earning a 4.

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

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

The description uses a specific verb ('Update') and resource ('existing issue in Linear'), and enumerates the modifiable fields (title, description, assignee, priority, workflow state). This clearly distinguishes it from siblings like create_issue, search_issues, and get_issue, as it specifically targets existing issues. The examples provide concrete usage patterns, making the purpose unmistakable.

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

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

The description states 'existing issue', implying it should be used for modifications, not creation. It lists the fields that can be updated, which signals when to use this tool. However, it does not explicitly mention alternatives (e.g., use create_issue for new issues) or exclusions, leaving some guidance implied rather than explicit. The examples show common scenarios but no direct comparison to sibling tools.

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