linear

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

Despite annotations only indicating readOnlyHint=false (write), the description adds extensive behavioral context: it's deprecated, for tiny files, verifies SHA-256, warns about data corruption, and explains the upload mechanism. This fully discloses the tool's behavior beyond what annotations provide.

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 lengthy but well-structured: deprecation notice, preferred alternative, critical warning, and verification examples. It front-loads the most important information. While verbose, every section serves a purpose, making it appropriate for the tool's complexity and risks.

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

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

The description covers usage, behavioral, and parameter aspects thoroughly. However, it does not specify the return value or output schema (e.g., whether an attachment ID is returned). Given no output schema, mentioning the expected result would improve completeness.

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

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

Schema coverage is 100%, but the description adds significant value for `sha256` and `size` parameters, detailing how to compute them and their purpose in verifying data integrity. It also reinforces the usage of `base64Content` with warnings and examples.

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 is a deprecated fallback for tiny files only, accepts base64 content, verifies SHA-256 checksum, and uploads. It explicitly names the preferred alternative, making the purpose 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 description provides explicit when-to-use (deprecated, tiny files only) and when-not-to-use (prefer alternative), along with critical warnings about copying base64 and verification steps. It gives concrete shell and PowerShell examples for correct invocation.

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=false (write operation), and the description confirms it creates an attachment row. It clarifies the tool's role in the workflow, notes that it does not handle file uploads, and warns about signed URL expiration. This adds significant behavioral context beyond what annotations provide.

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 with three short paragraphs. The first sentence immediately states the purpose, followed by a clear precondition checklist and a warning. No unnecessary words or repetition.

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 4 parameters, no nested objects, and no output schema, the description fully covers the tool's role in a multi-step workflow. It explains prerequisites, limitations, and error recovery, making it self-contained for an AI agent.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds critical workflow context: 'assetUrl' must come from prepare_attachment_upload, 'issue' can be ID or identifier (LIN-123), and 'title' defaults to filename or URL. This clarifies the provenance and format of parameters beyond schema descriptions.

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

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

The description clearly states 'Link an already-uploaded Linear assetUrl to an existing issue as an attachment.' It uses a specific verb ('link'), names the resource ('assetUrl' and 'issue'), and differentiates from sibling tools like prepare_attachment_upload and create_attachment by emphasizing the prerequisite steps.

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 instructs to use only after prepare_attachment_upload returns an assetUrl and the client uploads the file. It also states what the tool does not do ('This tool does not upload file content') and provides guidance on failure cases and alternatives ('rerun prepare_attachment_upload and upload again').

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 are minimal (no readOnly, no destructive, no idempotent). Description only repeats 'create', not explaining side effects like duplicate label behavior or required permissions.

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

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

Single sentence is concise and front-loaded, but could benefit from more structure given 6 parameters.

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

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

Given 6 parameters, no output schema, and sparse annotations, the description is too minimal. It doesn't explain label groups, team vs workspace, or return values.

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

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

Schema coverage is 100% with descriptions for all 6 parameters. The tool description adds no extra parameter information, so baseline score applies.

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

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

Description clearly states it creates a new Linear issue label, distinguishing it from listing or other create 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?

No guidance on when to use this tool, when not to, or alternatives like listing existing labels before creating. Lacks prerequisites (e.g., permissions, team context).

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

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

Annotations already declare destructiveHint=true. The description adds no extra behavioral context beyond confirming the delete action, such as permanence or security considerations. It does not contradict 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?

A single, efficient sentence with no fluff. Every word is necessary.

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

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

For a simple delete operation with one required parameter and no output schema, the description is complete. The destructiveHint annotation covers safety concerns.

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%; the parameter 'id' is described as 'Attachment ID' in the schema. The description merely says 'by ID', adding no additional meaning or constraints beyond what the schema provides.

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

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

The description clearly states the verb 'Delete' and the resource 'attachment', making the tool's purpose unambiguous. It distinguishes itself from sibling tools like create_attachment and get_attachment.

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

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

No explicit guidance on when to use this tool versus alternatives (e.g., delete_comment). The agent must infer from context. Implied usage is clear but no exclusions or when-not-to-use 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?

Discloses that root of inline description comments cannot be deleted, adding context beyond annotations. No contradiction with destructiveHint=true.

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: first declares action, second provides critical caveat. No redundancy.

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

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

For a simple delete operation with one parameter, description fully covers behavioral nuance. No output schema needed.

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?

Single parameter 'id' is well-described in schema. Description adds no extra meaning, but schema coverage is 100%, so baseline 3.

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

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

Clearly states 'Delete a Linear comment' with specific verb and resource. Distinguishes from siblings like save_comment and 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?

Explicitly tells when not to use (comments with non-null quotedText) and provides alternatives: delete replies individually or resolve the thread.

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 include destructiveHint=true, indicating destructive behavior. The description adds 'archive' in parentheses, suggesting the operation may not be permanent deletion but archiving, which provides behavioral context beyond 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 sentence that is front-loaded with the action and resource, conveying essential information without unnecessary 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 delete operation, the description covers the core purpose and parameter constraints. No output schema is needed for a delete tool, though the description does not mention what happens after deletion (e.g., success response). Annotations cover destructive nature, making it fairly complete.

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

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

Schema coverage is 100%, with descriptions for both parameters ('id' and 'type'). The description does not add any additional meaning or format details beyond what the schema provides, so baseline score of 3 is appropriate.

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

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

The description clearly states 'Delete (archive) a project or initiative status update.' It specifies the action (delete/archive) and the resource (status update with types project and initiative), distinguishing it from siblings like save_status_update and get_status_updates.

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 or when-not-to-use guidance. The description implies usage for deleting status updates but does not mention alternatives or prerequisites. Siblings like save_status_update and get_status_updates provide context, but the description itself lacks direct guidance.

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, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by specifying the source (markdown content from Linear) and the output nature ('images as viewable data'), which is helpful 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 two sentences with no wasted words. It front-loads the core purpose ('Extract and fetch images from markdown content') and then provides context. Very concise and 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?

The tool has one required parameter and no output schema. The description vaguely mentions 'receive the images as viewable data' without specifying the output format (e.g., URLs, base64). For a list operation with a return value, more detail on the result format is needed.

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

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

Schema coverage is 100% for the single parameter 'markdown', and the description in the schema is already present. The tool description does not add additional parameter details beyond what the schema provides, meeting the baseline of 3.

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

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

The description clearly states the tool extracts and fetches images from markdown content, listing specific use cases (screenshots, diagrams). It is specific and distinct from sibling tools like get_attachment or create_attachment.

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: 'Use this to view screenshots, diagrams, or other images embedded in Linear issues, comments, or documents.' It does not explicitly state when not to use or list alternatives, but the context is sufficient for a simple 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?

Annotations already indicate read-only, idempotent, non-destructive behavior. The description adds that the skill includes 'full markdown instructions', providing useful context about the return content. No contradictions.

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 that conveys the tool's purpose and key detail about the return value. No wasted 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 retrieval tool with one required parameter and full annotation coverage, the description is sufficiently complete. It mentions the return includes full markdown instructions, which compensates for the lack 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?

Schema coverage is 100% with a single parameter 'id' described as 'Agent skill ID'. The description reinforces the need for an ID but adds no new semantic meaning beyond the schema.

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

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

The description clearly states the verb 'retrieve' and the resource 'Linear Agent skill', and specifies it includes 'full markdown instructions'. It distinguishes itself from sibling 'list_agent_skills' by focusing on retrieval by ID.

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

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

The description makes it clear that this tool is for retrieving a specific agent skill by ID. However, it does not explicitly state when not to use it or compare it to alternatives like 'list_agent_skills', though the purpose is self-evident.

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, idempotentHint=true, destructiveHint=false, so the description adds little beyond stating it retrieves content by ID. It is consistent but not enriching beyond what structured fields provide.

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

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

The description is a single sentence that is efficiently front-loaded with the verb and resource, containing no wasted 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?

With one required parameter, complete annotations, and no output schema, the description is adequate for a simple retrieval tool. It could mention output format but is 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?

Schema coverage is 100% with the 'id' parameter described as 'Attachment ID'. The description restates 'by ID' without adding syntax or format details, meeting the baseline for high coverage.

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

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

The description uses a specific verb 'Retrieve' and identifies the resource 'attachment's content' by ID, clearly distinguishing it from sibling tools like create_attachment (creates) and delete_attachment (deletes).

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

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

The description implies usage when you need attachment content by ID, and the read-only nature is clear from annotations. However, it does not explicitly state when not to use it or mention alternatives like list tools for metadata, but context is sufficient for an agent.

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, idempotentHint=true, and destructiveHint=false. The description adds behavioral context by stating 'Exact lookup', confirming it is a single-record fetch operation. No contradictions.

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 concise sentences with the core purpose first and usage guidance second. No extraneous words or redundancy.

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

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

The tool is a simple lookup with one parameter. The description, combined with annotations and schema, provides sufficient context for an agent. The lack of output schema is acceptable for such a straightforward 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?

Schema coverage is 100% and includes a description of the urlOrId parameter. The tool description repeats the same list of acceptable formats, adding no new semantic information 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 'Exact lookup for a Linear diff', using a specific verb and resource. It distinguishes from sibling tools like list_diffs (list multiple) and get_diff_threads (threads), which have different purposes.

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 input types: 'Use with review URLs, GitHub PR URLs, Linear full identifiers, UUIDs, or slugs.' This tells the agent when to use the tool. However, it does not explicitly mention when not to use it or alternative tools for listing diffs.

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, idempotentHint=true, destructiveHint=false. Description adds 'exact lookup' behavior but doesn't elaborate on return format or pagination. With annotations present, this is adequate but not enhanced.

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

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

Two short sentences, front-loaded with core purpose. No redundant or extraneous text.

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

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

No output schema and no mention of return format or whether single thread or list is returned. Given the tool name 'get_diff_threads' (plural), it's unclear. Could be more complete.

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

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

Schema description coverage is 100%, so parameters are well-documented structurally. The description adds no extra semantic value beyond the schema, earning baseline score of 3.

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

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

Description clearly states 'exact lookup for diff threads', specifying verb and resource. It distinguishes from siblings like get_diff (returns diff) and list_comments (lists threads) by focusing on exact lookup and listing supported identifier types.

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?

Description lists various identifier formats (review URLs, GitHub PR URLs, etc.) that the tool accepts, but does not explicitly contrast with alternatives like list_comments or get_diff. Still provides clear context on when to use.

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, idempotentHint=true, and destructiveHint=false. The description adds the useful behavior that the document can be retrieved by either ID or slug, which is not captured in annotations. No contradictions. However, it does not describe what happens if the document is not found or the 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 concise sentence with no wasted words. It is front-loaded and immediately clear.

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 one parameter and rich annotations, the description is mostly complete. It covers the what and how. Missing details like error handling or return format, but these are minor 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?

Schema description coverage is 100% (the parameter 'id' is described as 'Document ID or slug' in the schema). The tool description ('by ID or slug') adds no new meaning beyond what the schema already 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?

The description clearly states the tool retrieves a Linear document by ID or slug. It uses a specific verb ('Retrieve') and resource ('document'). While it does not explicitly distinguish itself from sibling tools like 'list_documents', the context implies it's for fetching a single document, but lacks explicit 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 provides no guidance on when to use this tool versus alternatives. There is no mention of conditions, prerequisites, or when not to use it. The user must infer from the name and context.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read. The description adds context that the response includes attachments and git branch name, which is valuable information beyond what annotations provide. No contradictions found.

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 main purpose. Every word contributes meaning, and there is no redundant or unnecessary text.

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

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

Given that there is no output schema, the description provides a partial hint about return values ('including attachments and git branch name'). The annotations cover behavioral safety. The description could mention error conditions or when the issue doesn't exist, but for a standard get-by-id tool, it is largely complete.

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

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

Schema description coverage is 100%, so baseline is 3. The description adds meaning by highlighting that the tool retrieves 'detailed information' and specifically 'attachments and git branch name,' indicating the response contents. This enhances understanding beyond the parameter descriptions in the schema.

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

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

Purpose is explicitly stated: 'Retrieve detailed information about an issue by ID, including attachments and git branch name.' It clearly identifies the verb (retrieve), resource (issue by ID), and scope (including attachments and git branch). Among siblings, it distinguishes from list_issues (list vs single), get_attachment (specific attachment), and save_issue (update).

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

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

The description implies usage for retrieving a single issue by ID, but it does not explicitly state when to use this tool versus alternatives like list_issues (for multiple issues) or get_document (for documents). No exclusions or prerequisites are mentioned, though the requirement of 'id' is clear from the schema.

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 and destructiveHint=false, so the agent knows this is a safe read operation. The description adds the detail that status can be retrieved 'by name or ID', providing useful context beyond what annotations provide. However, it does not disclose any additional behavioral traits such as error cases or data freshness.

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 wasted words. It front-loads the purpose and effectively communicates the tool's function.

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 low complexity (3 required params, simple read operation) and the presence of annotations indicating read-only and idempotent behavior, the description is adequate. It lacks details about the return format or whether the status details include all fields, but this is acceptable for a get-by-ID tool without an output schema. The sibling tools list shows related tools, but no further context is needed.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters (id, name, team). The description mentions retrieval 'by name or ID' but does not explain how name and team interact (e.g., whether name is unique per team). This adds marginal value 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 uses a specific verb 'retrieve' and resource 'issue status', and specifies the method 'by name or ID'. It clearly distinguishes from sibling tools like 'list_issue_statuses' (which lists all statuses) and 'get_issue' (which gets an issue details).

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

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

No explicit guidance on when to use this tool versus alternatives. The description implies it is for getting a single status's details, but does not mention when not to use it or provide alternative tool names. The context signals show siblings like 'list_issue_statuses' which could be used to list all statuses, but no direct comparison is made.

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, idempotentHint=true, and destructiveHint=false, so the description does not need to repeat those. The description adds that retrieval is by ID or name, which is consistent. However, it does not disclose any additional behavioral traits such as error handling or data freshness.

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

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

The description is a single sentence that immediately conveys the tool's purpose. It is front-loaded with the verb and resource, containing no unnecessary words. Every part is essential.

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 low complexity, full schema coverage, and comprehensive annotations, the description is mostly sufficient. It could optionally hint at the fields returned (since there is no output schema), but the current level is adequate for an agent to select and invoke the tool correctly.

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

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

Schema coverage is 100%, so the parameters are already well-described. The description mentions 'by ID or name', aligning with the query param, but adds no new semantic details beyond the schema. A baseline score of 3 is appropriate.

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

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

The description uses a specific verb 'Retrieve' and clearly identifies the resource as 'details of a specific milestone by ID or name'. It effectively distinguishes from sibling tools like list_milestones (which lists all milestones) and save_milestone (which creates/updates), making the tool's purpose 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 description implies usage when you need a single milestone's details, but it does not explicitly state when to use this tool versus alternatives (e.g., using list_milestones to find an ID first). No exclusions or prerequisites are mentioned, leaving some inference required.

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

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

The description does not add behavioral context beyond what annotations already provide (readOnlyHint, idempotentHint, destructiveHint). While it does not contradict the annotations, it also fails to disclose additional traits like response behavior or side effects, which the annotations already cover adequately.

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 (6 words) that conveys the core purpose without superfluous information. Every word earns its place, making it highly concise and effective.

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

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

Given that there is no output schema, the description should ideally clarify what 'details' are returned (e.g., fields, structure). It also does not address the context of use relative to sibling tools. It is minimally adequate but not fully complete.

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

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

Schema documentation covers all parameters (100% coverage), so the description does not need to add parameter detail. It adds no extra meaning beyond the schema, earning a baseline score of 3.

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

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

The description clearly states the action ('Retrieve details') and the resource ('a specific project in Linear'). It effectively distinguishes the tool from siblings like 'list_projects' (which lists all) and 'get_issue' (different resource), meeting the criteria for a specific verb+resource pair.

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

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

No guidance is provided on when to use this tool versus alternatives such as 'list_projects' or 'get_issue'. There is no mention of prerequisites, context, or exclusions, so the agent lacks direction for 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 provide readOnlyHint, idempotentHint, destructiveHint. Description adds no new behavioral context; no contradiction.

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

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

Single sentence, front-loaded with verb and resource, no unnecessary 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 retrieval tool with two parameters and rich annotations, description is adequate; could mention return value but not strictly required given common pattern.

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

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

Schema coverage is 100% and already describes both parameters sufficiently. Description adds no extra parameter meaning beyond what schema provides.

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

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

Description clearly states 'Retrieve details of a release by ID or slug.' Verb (retrieve) and resource (release) are specific and distinct from siblings like list_releases or get_release_note.

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

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

Implied usage for fetching a single release by identifier; no explicit when-not or alternatives mentioned, but standard pattern for get-by-id tools.

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 safe, read-only, idempotent behavior. Description adds detail about markdown content, but does not disclose any additional behavioral traits beyond 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?

Single sentence, 10 words, front-loaded with the action and resource. No 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 low complexity, rich annotations, and high schema coverage, the description is mostly complete. Missing guidance on usage context and the optional parameter, but adequate for a simple retrieval tool.

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

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

Schema coverage is 100%, so description does not need to compensate. Description mentions 'by ID or slug' which matches the 'id' parameter description. The 'includeReleases' parameter is not mentioned, but schema already documents it adequately.

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?

Clear verb (retrieve) and resource (release notes) with specific method (by ID or slug) and content type (markdown). However, no explicit differentiation from sibling tools like list_release_notes or save_release_note.

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

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

No explicit guidance on when to use this tool versus alternatives. The description implies usage when you have an ID or slug, but does not advise against using it for listing or modification tasks.

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, idempotentHint=true, destructiveHint=false. Description adds no further behavioral details beyond the read nature, but is consistent.

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

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

Single sentence, directly conveys the core functionality without extraneous 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?

Given 11 parameters and no output schema, the description is adequate but lacks details on interaction of parameters (e.g., id + filters), pagination behavior, or output format.

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 provides 100% parameter coverage with descriptions. The description adds a usage pattern (id vs filter) but no new param-specific semantics beyond schema.

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

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

The description clearly states the tool can list or get specific status updates by ID, with filtering. It distinguishes from sibling tools like save_status_update and delete_status_update.

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 guidance on using `id` for a single update or filters for listing. Does not explicitly exclude use cases or mention alternatives, but sufficient for basic 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the tool is known to be read-only. The description adds minimal behavioral context beyond 'retrieve details', missing potential error conditions or auth requirements.

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 of 8 words, front-loading the action and resource. No wasted 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 tool with one well-documented parameter, the description is adequate. It could mention the return format but is complete enough without 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?

Schema coverage is 100% with a clear description for the only parameter. The tool description does not add any extra meaning or usage hints 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 uses the specific verb 'Retrieve' and resource 'details of a specific Linear team', clearly distinguishing it from list_teams and other 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 clearly implies retrieving a single team, contrasting with list_teams for listing all teams, but does not explicitly mention when not to use it or state 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, which fully cover the behavioral profile. The description adds no extra behavioral context beyond what annotations provide, but is consistent with them.

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

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

The description is a single sentence that conveys the purpose without any extraneous words. It is appropriately concise for a simple retrieval tool.

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

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

Given the tool's simplicity (one fully-documented parameter, clear annotations, no output schema), the description is complete enough for an agent to understand its function. A slight improvement could be mentioning that it returns user details, but the schema already covers input.

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 'query' is fully described in the schema with its purpose and accepted values (User ID, name, email, or 'me'). The description does not add additional meaning beyond what the schema provides, so baseline 3 applies.

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

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

The description clearly states the verb 'Retrieve' and the resource 'details of a specific Linear user'. It effectively distinguishes this tool from sibling tools like 'list_users' (which lists multiple users) and other get_ tools for different resources.

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 such as 'list_users' or 'search_documentation'. No context is given about prerequisites, exclusions, or typical use cases.

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, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context (e.g., pagination, caching, rate limits) beyond stating the resource. Annotation coverage is sufficient for a simple read-only list, so a baseline 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?

The description is a single sentence with no fluff. Every word earns its place, achieving maximum 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 list tool with clear annotations and self-explanatory parameters, the description is mostly complete. However, no output schema is provided, and the description omits return format details, though the tool name and context signals largely compensate.

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% with inline descriptions for all three parameters (limit, cursor, orderBy). The tool description does not add any additional parameter meaning beyond the schema, so a baseline 3 is justified.

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 the resource ('Linear Agent skills') and specifies the scope ('available to the authenticated user'). It distinguishes from sibling list tools by naming a specific entity, but could be slightly more precise.

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 alternative list tools or how it relates to other skills-related operations. No when-not-to-use or alternative tool mentions.

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 (readOnlyHint, destructiveHint, idempotentHint) already indicate safety. Description adds valuable context: it returns both top-level and inline comments, and inline comments have a non-null 'quotedText' field. No contradictions with annotations.

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

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

Two sentences, no filler. First sentence covers purpose and all parent types; second sentence explains the exact-one constraint and the important distinction between comment types. Essential information front-loaded.

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

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

For a moderately complex tool with 10 parameters and no output schema, the description covers the most critical aspects: parent selection, comment types, and conditional statusUpdateType usage. Missing details on pagination/sorting (already in schema) but overall comprehensive.

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

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

Schema coverage is 100%, but description adds critical semantics: the mutual exclusivity of parent IDs (reinforced as a group), the return type distinction (inline vs. top-level), and the conditional use of statusUpdateType. These go beyond the schema's per-parameter descriptions.

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

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

Clearly states the verb 'list' and resource 'comments', enumerates all valid parent entities (issue, project, initiative, document, milestone, status update), and distinguishes from sibling tools that list other resources (e.g., list_issues, list_projects). No 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?

Explicitly states the constraint 'Provide exactly one of...' and explains the behavior difference between top-level and inline comments. Does not explicitly exclude use for other contexts or mention alternatives like get_diff_threads, but the parent variety and constraint are sufficient for correct 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?

Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows this is a safe read. The description adds minimal behavioral context beyond that (e.g., no mention of pagination, error handling, or that it returns a list of cycles). Given the annotation coverage, the description is adequate but not enriched.

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

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

The description is a single, front-loaded sentence that efficiently conveys the core purpose. It is not verbose, but could be slightly improved by adding a note about optional filtering. Overall, it is concise and 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's simplicity (2 parameters, no output schema, no nested objects), the description is minimally adequate. It does not mention return type (list of cycles) or usage context (e.g., that teamId is required). Without an output schema, the description should hint at the structure, but it doesn't. Hence, it is complete only at a basic level.

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%, meaning the schema already describes both parameters (teamId and type). The description does not add any extra meaning (e.g., what a cycle is, the format of teamId, or the effect of the type filter). Thus, it adds no value beyond the schema, earning the baseline score of 3.

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

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

The description clearly states the action ('Retrieve'), the resource ('cycles'), and the scope ('for a specific Linear team'). It distinguishes this tool from siblings as no other sibling tool targets cycles, and the specificity of requiring a team ID is evident.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., other list tools like list_issues or list_milestones). There is no mention of prerequisites, limitations, or when not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds minimal context (authentication scope), but does not reveal additional behavioral traits beyond what annotations provide.

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

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

Single sentence of 12 words, no redundancy or fluff. Efficiently communicates the core function.

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

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

Despite lacking output schema and not describing return format, the tool is straightforward (list operation) with well-documented parameters. Some minor gaps but mostly complete given 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?

All 7 parameters are fully described in the input schema (100% coverage). The tool description itself adds no additional parameter semantics, so baseline score of 3 applies.

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

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

Clearly states verb 'List', resource 'Linear diff pull requests', and scope 'visible to the authenticated user'. Unambiguous and distinct from sibling 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?

No guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. The description only states what it does, not when or why to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, making the tool's safety profile clear. The description adds no extra behavioral insight, such as pagination behavior, rate limits, or authentication requirements. Since annotations cover the core traits, the score is adequate but unremarkable.

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 extraneous words. It is concise and immediately conveys the core action, though it could include a brief mention of filtering capabilities without significant bloat.

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

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

Given the tool's complexity (11 parameters, no output schema, many siblings), the description is too minimal. It omits crucial context such as pagination (cursor), available filters, and return type (likely a list of document objects). This incompleteness may hamper correct invocation by an AI agent.

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

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

The input schema has 100% description coverage for all 11 parameters, each with clear definitions. The tool description adds no additional meaning beyond what the schema already provides, meeting the baseline expectation but offering no extra value.

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

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

The description clearly states the verb 'list' and resource 'documents' within the Linear workspace, making the purpose unambiguous. However, it does not differentiate from sibling tools like 'list_issues' or 'search_documentation', which could lead to confusion if the agent needs to choose between listing similar resources.

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, such as 'search_documentation' for full-text search or 'get_document' for a single document. It also lacks prerequisites, exclusions, or context about typical use cases, forcing the agent to rely solely on schema parameters.

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, idempotentHint, and destructiveHint. The description adds scope context ('workspace or team') but does not disclose pagination behavior, default scope, or response structure beyond the schema.

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 are immediately clear.

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 5 optional parameters and no output schema, the description leaves the agent to infer return format and filtering behavior from parameter descriptions. It is adequate but lacks detail on response fields or pagination flow.

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

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

Schema description coverage is 100%, so parameters are already well-documented in the schema. The description does not add any parameter-specific meaning beyond the general scope mention.

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

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

The description clearly states the verb 'List' and the resource 'available issue labels' with scope 'in a Linear workspace or team', distinguishing it from siblings like 'list_project_labels' and 'create_issue_label'.

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

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

No guidance on when to use this tool versus alternatives such as 'list_project_labels' or other list tools; no when-not-to-use or prerequisites are mentioned.

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 indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is known. The description adds no extra behavioral details (e.g., pagination, rate limits). It does not contradict annotations, so score is at baseline.

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: one for core purpose, one for key parameter guidance. No fluff, front-loaded, every sentence earns its place. Ideal 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?

With 17 parameters and no output schema, the description is minimal. It doesn't mention default limit, max, pagination (cursor), or common filter combinations. However, the schema details these, so the description is not incomplete in a harmful way, but it could add more operational context.

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

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

Schema coverage is 100% with descriptions for all 17 parameters. The description adds meaning for the assignee parameter by explaining special values 'me' and 'null', which is valuable and beyond the schema's generic description. No other parameters gain extra context, but this single addition justifies a higher score.

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

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

Description clearly states 'List issues in the user's Linear workspace', identifying the resource and action. It gives specific guidance on using 'me' and 'null' for the assignee parameter, adding value. However, it does not explicitly distinguish from sibling tools like get_issue, but that is implied by the plural 'list' vs singular 'get'.

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?

Description provides specific parameter usage ('For my issues, use "me" as the assignee. Use "null" for no assignee.') but no general guidance on when to use this tool versus alternatives (e.g., get_issue for a single issue, or search_documentation for documentation). Context is implied but not explicitly 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 already declare the tool as read-only, idempotent, and non-destructive. The description adds no additional behavioral context beyond what annotations provide, which is adequate but not enhanced.

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 key action and resource, with no unnecessary words. It is perfectly efficient for its 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?

Despite the simple structure and annotations, the tool has no output schema or description of return values. The agent is left unaware of what the response contains (e.g., list of status names, objects), which is a gap for a listing tool.

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

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

The input schema has 100% coverage with a single parameter 'team' described as 'Team name or ID'. The description does not add further meaning beyond the schema, meeting the baseline but not exceeding it.

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

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

The description clearly states the verb 'List' and the resource 'available issue statuses in a Linear team', making the tool's purpose unambiguous. It is distinct from siblings like 'get_issue_status' which retrieves a single status.

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 like 'get_issue_status' or other list tools. It lacks explicit context for choosing this tool over similar ones.

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

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

The description aligns with annotations (readOnlyHint true, destructiveHint false) but adds no behavioral context beyond listing milestones. No mention of pagination, result format, or other traits.

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 effectively conveys the tool's purpose with no wasted 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 list tool with one required parameter, the description covers core purpose. However, it lacks details like result structure or pagination, which would enhance completeness.

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

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

Schema coverage is 100% and describes the 'project' parameter. The description adds no additional meaning, only echoing the context already implied by 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 'List all milestones in a Linear project,' which specifies the action (list), resource (milestones), and context (project). It effectively distinguishes from sibling tools like get_milestone (single) and save_milestone (create/update).

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, such as get_milestone for a single milestone. Usage is implied but not explicitly 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 already provide read-only, idempotent, non-destructive hints. Description adds no further behavioral context (e.g., pagination behavior or rate limiting), but does not contradict 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?

Single sentence, no filler, perfectly front-loaded with purpose. 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 with full schema coverage and annotations, the description is adequate. Missing only minor elements like pagination hint, but overall complete.

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

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

Schema coverage is 100% with descriptions for all 4 parameters. The description does not add extra meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Description explicitly states 'List available project labels in the Linear workspace', using a specific verb and resource ('project labels') that clearly distinguishes it from sibling tools like list_issue_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 on when to use this tool versus alternatives (e.g., list_issue_labels). The description only states what it does without excluding any context or providing usage criteria.

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 indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true. Description adds minimal behavioral context ('in the user's Linear workspace'), but no contradictions. The description does not elaborate on return format or pagination 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?

Single sentence, efficient and front-loaded. However, it is minimal and could include key filtering or sorting capabilities without becoming verbose.

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

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

Given 14 parameters and no output schema, the description is adequate for a straightforward list operation but lacks hints about filtering, sorting, or pagination. The schema provides details, so the description does not need to repeat them, but it could summarize capabilities.

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

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

Schema description coverage is 100%, so the schema already documents all 14 parameters. The description does not add any parameter-level meaning beyond what is in the schema. Baseline 3 is appropriate.

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

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

Description clearly states 'List projects in the user's Linear workspace', specifying verb, resource, and scope. This distinguishes it from sibling list tools like list_issues or list_diffs.

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

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

No guidance on when to use this tool vs alternatives. With sibling tools like list_issues or list_documents, the description should indicate when listing projects is appropriate or what differentiates it.

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

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

Annotations already indicate read-only, idempotent, non-destructive. The description adds that results can include content, archived items, and associated releases, exceeding annotation 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?

Single, concise sentence that is front-loaded with the main action. No wasted words, though could be slightly more 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?

With 11 parameters fully described in schema, the description covers basic functionality but omits mentioning pagination (cursor), ordering, or return shape. For a complex list tool, more context would help.

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

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

Schema description coverage is 100%, so each parameter is described. The description adds 'optionally filtered by pipeline or release' but does not add meaning beyond the schema for individual 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 'List release notes in the workspace' with optional filters, distinguishing it from sibling tools like get_release_note (single item) and save_release_note (create/update).

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

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

No guidance on when to use this tool vs alternatives. There are many list tools among siblings, and no explicit when-not-to-use or alternative suggestions.

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 indicate read-only and idempotent behavior. Description adds no extra behavioral details (e.g., pagination, limit handling). Given annotations, this is adequate but not enhanced.

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

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

Single sentence, no unnecessary words. Purpose is front-loaded and clear.

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 12 parameters and no output schema, the description lacks context on common combinations, query patterns, or response format. The tool is complex but the description is minimal.

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?

All 12 parameters have schema descriptions, so baseline is 3. The tool description adds no additional meaning beyond what the schema provides.

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

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

Description clearly states 'List release pipelines in the workspace', with a specific verb and resource. It distinguishes from sibling list tools which target other entities (issues, projects, etc.).

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

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

No guidance on when to use this tool vs others, no exclusions or alternatives mentioned. The minimal description assumes the agent knows when to call it.

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

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

Annotations already indicate readOnlyHint=true, destructiveHint=false, and idempotentHint=true, establishing the tool's safety profile. The description adds context about optional filtering but does not reveal any additional behavioral traits beyond what annotations provide.

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

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

The description is a single sentence, which is concise but incomplete. It front-loads the main action and a few filters but sacrifices comprehensiveness. It could be restructured to either list all filters or use a more general phrase like 'multiple filtering options'.

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 13 parameters and no output schema, the description should provide a more complete overview of available filters. It fails to cover the full range of filtering capabilities, making it insufficient for agents to understand the tool's full scope.

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 100% of parameters with descriptions, so baseline is 3. However, the tool description only mentions four filters (pipeline, stage, version, text) while omitting nine others (limit, cursor, orderBy, createdAt, updatedAt, hasReleaseNotes, includeArchived, includeReleaseNotes, stageType). This incomplete listing could mislead agents into thinking only those four filters exist.

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 releases with optional filtering. It identifies the resource (releases) and the action (list), which is specific enough given the sibling tools list different entities. However, it does not explicitly differentiate from other list tools, so it's not a 5.

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 like get_release or list_release_notes. It only describes the functionality without contextual usage advice.

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 readOnlyHint, idempotentHint, and destructiveHint. The description adds no additional behavioral context beyond 'list teams', such as pagination behavior or that results are paginated.

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 gets straight to the point. However, it is somewhat too sparse, missing useful details about pagination and return format.

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 7 optional parameters and no output schema, the description should explain that the tool returns a paginated list of team objects. It does not cover return format or pagination behavior.

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

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

Schema coverage is 100%, so the description adds minimal meaning beyond 'in the user's Linear workspace'. The schema already documents all 7 parameters with descriptions.

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

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

The description clearly states 'List teams', which is a specific verb-resource combination. It distinguishes itself from the sibling tool 'get_team' (singular) and other list tools like '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 usage for retrieving all teams, but does not provide explicit guidance on when to use this tool versus alternatives like 'get_team' or searching. No filtering or pagination advice is given.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, making the safe read-only nature clear. The description adds no extra behavioral context beyond what annotations provide.

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, clear sentence with no unnecessary words. Efficiently communicates the core 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?

Given the straightforward list operation with 5 fully-described parameters and annotations, the description is adequate. However, it could mention that the response is a list of users, but the lack of output schema is partially mitigated by the parameter 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 100%, so the schema already documents all parameters. The description does not add additional meaning or clarify parameter usage 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 verb 'Retrieve' and the resource 'users in the Linear workspace'. It distinguishes from sibling tools like 'get_user' (single user) and 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 description implies usage for listing users but does not explicitly state when to use this tool versus alternatives like 'get_user' or other list tools. No when-not or alternative guidance is 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?

Discloses behavioral traits beyond annotations: signed URL must be used within 60 seconds, headers must be sent verbatim (including casing), and omitting/modifying headers returns 403. No contradiction with annotations (readOnlyHint=false, etc.).

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?

Well-structured with clear workflow steps and examples. Slightly long but every sentence earns its place. Could be trimmed slightly without losing 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?

Comprehensive for a tool without output schema: explains what the tool returns (uploadRequest.url and headers), the full workflow, and troubleshooting tips. No gaps given the complexity.

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

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

Schema coverage is 100%, so baseline is 3. Description adds context for size (exact bytes, <2GB) and filename example, but does not significantly enhance understanding beyond schema descriptions.

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

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

The description states it prepares a direct Linear file upload for an existing issue, with a clear verb and resource. It distinguishes from sibling tools like create_attachment and create_attachment_from_upload by outlining the workflow and when to call each.

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 explicit step-by-step workflow, including when to use this tool before PUT and then call create_attachment_from_upload. Warns not to batch multiple prepare calls to avoid signed URL expiration, and gives usage constraints like 60-second expiry.

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 indicate readOnlyHint=false, destructiveHint=true, and idempotentHint=true. The description adds no behavioral context beyond the basic action, such as side effects, permissions, or the permanence of resolution. It partially explains the 'resolved' parameter's effect (resolve vs reopen) but omits details on state changes.

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, well-structured sentence with no unnecessary words. It front-loads the core function and is appropriately concise.

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

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

The description covers the basic functionality but lacks context about what 'resolved' means (e.g., visibility, notifications), prerequisites (e.g., ownership), and boundary conditions (e.g., calling on already resolved thread). With no output schema and a destructive hint, more completeness would be beneficial.

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

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

Schema coverage is 100% with clear parameter descriptions. The tool description does not add any new semantics beyond the schema. Given the high schema coverage, a baseline score of 3 is appropriate.

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

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

The description clearly states the action (resolve or reopen) and the resource (top-level comment thread on a Linear diff). It distinguishes from sibling tools like delete_comment or save_diff_comment by specifying 'top-level comment thread' and the dual resolve/reopen functionality.

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. It does not explain when to resolve versus reopen, nor does it mention prerequisites or scenarios where delete or save might be more appropriate.

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

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

The description adds significant behavioral context beyond annotations: it explains the conditional behavior of parameters, how statusUpdateType is validated, and that parent fields are ignored when id or parentId is provided. Annotations indicate destructiveHint=true, which aligns with create/update operations.

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, well-structured paragraph that front-loads the main purpose and logically progresses through different modes. Every sentence adds value, and there is no redundancy.

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

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

Given the tool's complexity (10 parameters, conditional logic), the description covers all necessary cases: create, update, reply, and the various entity types. It explains edge cases like statusUpdateType rejection and inheritance of thread type. No output schema exists, but the description adequately addresses the input behavior.

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

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

Schema description coverage is 100%, but the description adds crucial semantic context: the interplay between parameters, the requirement for exactly one parent when creating a thread, the special handling of statusUpdateType, and the format of body (Markdown). This goes well 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 creates or updates comments on multiple Linear entities. It distinguishes between creating a new thread (using entity IDs) and replying (using parentId), and between creating and updating (via id). This is specific and differentiates from siblings like 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 description provides explicit guidance on which parameters to use for different scenarios (new thread vs reply, update vs create). It explains when fields are ignored or rejected. However, it does not explicitly mention when to use an alternative tool (e.g., delete_comment for deletion), which would complete the guidance.

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 indicate destructiveHint=true; description adds that it creates or updates, reparents on update, and specifies required parents. This adds useful behavioral context 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?

Three sentences, front-loaded with the main purpose, then conditions. No redundant or extraneous information. Efficiently conveys all necessary usage rules.

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

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

Covers main behaviors (create/update, parent constraints, reparenting) adequately for a tool with 10 parameters and no output schema. Could mention error handling or response format, but not essential.

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

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

Schema coverage is 100%, giving a baseline of 3. Description adds crucial constraints: title required when creating, exactly one parent must be specified, and reparenting behavior on update. This adds significant meaning.

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 'Create or update a Linear document' which is a specific verb-resource pair. The description differentiates it from sibling tools like get_document or list_documents by focusing on mutation.

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?

Explicitly distinguishes between create and update based on presence of `id`. States required fields for creation (title and exactly one parent). Does not explicitly mention when not to use this tool, but the conditions are 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?

Annotations set destructiveHint=true and readOnlyHint=false. The description amplifies this by detailing which parameters are append-only (links, blocks, blockedBy, relatedTo, addReleases) and which are fully replaced (labels). It also clarifies behavior on omit vs null for estimate and labels, providing critical context beyond 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, efficient paragraph that front-loads the core purpose (create/update) and then covers essential behavioral nuances and parameter tips. Every sentence adds unique value, no redundancy.

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

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

Given 26 parameters, no output schema, and no nested objects, the description covers all critical behavioral distinctions: create vs update, required fields, append-only vs replacement semantics, parameter tips, and null vs omit behaviors. It is complete for effective agent usage.

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 100% schema coverage, parameters already have descriptions. The description adds extra value: it explains that 'assignee' accepts ID, name, email, or 'me', warns against 'assigneeId', gives markdown usage for description, and details create vs update semantics for estimate and labels. This goes well 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 it creates or updates a Linear issue based on the presence of 'id', and distinguishes between the two modes. It specifies required fields for creation and highlights a key naming nuance (assignee vs assigneeId).

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 instructs when to use the tool (create vs update), notes required fields, and gives a parameter tip (assignee). However, it does not explicitly exclude scenarios where sibling tools like save_comment or create_attachment would be more appropriate, though that is generally implied.

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 indicate destructiveHint true (potential data loss) and readOnlyHint false. The description adds behavioral detail: id-driven create/update logic and the requirement for 'name' when creating. This goes beyond the annotations, explaining the conditional 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 extremely concise—two sentences—and front-loads the core purpose. Every word 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?

The description covers the core behavior (create/update, id logic, name requirement) and is sufficient for a mutation tool with 5 parameters. It lacks explanation of return values or error conditions, but given no output schema and the tool's straightforward nature, it is reasonably complete.

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

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

Schema coverage is 100%, but the description adds meaning beyond raw schema by explaining the conditional use of 'id' and the requirement for 'name' when creating. This clarifies parameter semantics that are not obvious from the schema alone.

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

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

The description clearly states the tool creates or updates a milestone, distinguishing between the two based on presence of 'id'. It identifies the resource (milestone) and the action (save), and differentiates from sibling tools like get_milestone or list_milestones which are read-only.

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 for when to use the tool (create vs update based on id) and conditions ('name' required for creation). It does not explicitly state exclusions or alternatives, but the sibling list implies other tools for reading or listing milestones.

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 indicate destructive behavior (destructiveHint=true). The description adds valuable behavioral context beyond annotations by explaining the upsert logic and the required parameters for creation. This provides a clear understanding of what the tool does without contradicting 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 concise at two sentences, with no wasted words. It is front-loaded with the primary purpose (create or update) and efficiently provides essential behavioral details, making it easy for an AI agent to quickly grasp the tool's function.

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

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

Given the tool's complexity (20 parameters, no output schema), the description covers the core behavior and creation constraints adequately. It does not describe return values or error conditions, but these are not expected when no output schema is provided. Overall, it provides sufficient context 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?

The schema already provides detailed descriptions for all 20 parameters (100% coverage), so the burden on the description is lower. The description adds semantic value by clarifying the role of the 'id' parameter (create vs. update) and the required conditions for creation, which aids correct usage.

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 'Create or update a Linear project' using a specific verb and resource, and distinguishes the two operations based on the presence of the 'id' parameter. This effectively differentiates it from sibling tools like 'save_issue' or 'create_attachment'.

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 by specifying that 'name' and at least one team are required when creating, and that providing an 'id' triggers an update. However, it does not explicitly state when to use this tool over alternatives or when not to use it, which would enhance guidance.

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

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

The description discloses the create/update behavior and notes that release status is modeled as the pipeline stage. The annotations already indicate destructiveHint=true and readOnlyHint=false, so the description adds context about the status modeling. It does not detail potential side effects of updates, but the annotation covers the safety profile adequately.

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 sentences, front-loading the main purpose and then adding key details. Every sentence is necessary and contributes to understanding.

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 12 parameters and complete schema coverage, the description adequately covers the core functionality. It could be more explicit about update semantics (e.g., partial vs full replace), but for a create/update tool with good field descriptions, this is sufficient.

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 100% schema description coverage, the baseline is 3. The description adds value by summarizing the create/update logic and highlighting that 'name' and 'pipeline' are required when creating, which is not explicit in the schema's individual field descriptions.

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

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

The description clearly states 'Create or update a release' and distinguishes between the two based on the presence of the 'id' parameter. It also mentions the effect on release status (modeled as pipeline stage), which is specific and actionable.

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 explains when to use the tool for creating (no id) vs updating (with id), and specifies that 'name' and 'pipeline' are required when creating. However, it does not provide guidance on when not to use the tool or alternative tools, though sibling tools are distinct resources.

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 indicate `readOnlyHint=false` and `destructiveHint=true`, so the description's 'create or update' is consistent. The description adds the create/update distinction but does not elaborate on what data is affected (e.g., whether updates replace or merge content). Given the annotations already convey the destructive nature, the description adds moderate 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 extremely concise—two sentences covering the core logic and key requirements. No wasted words, and the most important information (create vs. update condition) is front-loaded.

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

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

Given the tool's moderate complexity (7 parameters, create/update logic) and the existence of full schema descriptions and annotations, the description is mostly complete. It explains the essential behavior and parameter requirements. However, it lacks information on return values or error scenarios, but the absence of an output schema reduces the burden.

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

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

Schema coverage is 100% with each parameter described. The description goes beyond by clarifying the relationship between parameters: for creation, `pipeline` and either `releases` or `rangeFromRelease`/`rangeToRelease` are required. This adds value beyond the individual parameter descriptions, providing interplay semantics.

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

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

Description clearly states it creates or updates release notes, with specific verb 'Create or update' and resource 'release notes'. It distinguishes between create and update based on the presence of 'id'. This is unambiguous and differentiates from sibling tools like 'list_release_notes' or 'get_release_note'.

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 create vs. update (if `id` is provided). It specifies required parameters for creation (`pipeline` and either `releases` or a release range). However, it does not state when not to use this tool or mention alternatives, but since it's the only tool for saving release notes, the guidance is clear and 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?

The description adds some behavioral context (create/update distinction) beyond the annotations (destructiveHint: true), but it does not elaborate on side effects, return values, or safety considerations. The annotations already indicate a destructive nature, so the description's additional value is modest.

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 sentences, front-loading the purpose and providing essential usage guidance in a clear, compact form. Every word earns its place with no redundancy or filler.

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

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

Despite having 7 parameters and no output schema, the description covers the key behavioral distinction (create vs. update) and leverages thorough schema descriptions. It lacks details on return values or validation, but for a straightforward CRUD tool it is 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?

Schema description coverage is 100%, so the baseline is 3. The description adds minimal new information beyond the schema, primarily the usage pattern for 'id'. Other parameters are adequately described in the schema but not enhanced by the description.

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

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

The description clearly states the tool creates or updates a status update, specifying the action and resource. It distinguishes between create and update by mentioning the role of the 'id' parameter, and among sibling tools (e.g., delete_status_update, get_status_updates) it is unique in handling save operations.

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

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

The description provides direct guidance on when to create vs. update (omit id vs. provide id). However, it does not explicitly state when not to use this tool, such as for deletions (handled by delete_status_update) or other operations, nor does it mention prerequisites or context like required permissions.

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, idempotentHint, and destructiveHint, so the description's additional context that the tool searches documentation adds some value but does not detail behavior like pagination or result 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, concise sentence that communicates the core purpose without unnecessary words. However, it could include more details without becoming verbose.

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

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

For a simple search tool with two parameters and no output schema, the description is minimally adequate. It covers the basic purpose but does not explain the 'page' parameter's behavior or what the search results contain.

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

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

Input schema has 100% coverage with descriptions for both 'query' and 'page'. The tool description does not add any additional meaning or usage hints for these parameters beyond what the schema provides.

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

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

The description clearly states the verb 'Search' and the resource 'Linear's documentation', and the purpose 'to learn about features and usage'. This distinguishes it from related tools like get_document (retrieve specific doc) and list_documents (list all docs).

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

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

No guidance on when to use this tool versus alternatives like get_document or list_documents is provided. The description lacks explicit context for when search is appropriate.

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 destructiveHint=true and readOnlyHint=false. Description adds the three decision types, but these are also in the schema enum. No additional behavioral context beyond that.

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

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

Single sentence with clear front-loading of key actions. No unnecessary 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 review submission tool with good annotations and schema, the description is adequate. Lacks return value info, but no output schema exists. Sibling tools cover related actions, so context is sufficient.

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%, and the description essentially restates the enum values. No extra semantics added beyond what the schema already provides.

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

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

The description clearly states the three actions (approve, request changes, or comment) on a Linear diff, using specific verbs and the resource. It distinguishes from sibling tools like merge_diff or get_diff by focusing on review submission.

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?

Implies usage for submitting reviews on diffs, but lacks explicit when-not-to-use or alternative tool guidance. Context from name and sibling list helps, but no direct exclusionary language.

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