linear

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

Annotations indicate this is a non-readOnly, non-destructive, non-idempotent, non-openWorld operation, covering basic behavioral traits. The description adds context about the upload method (base64-encoded content) and target (Linear issue), which isn't in annotations. However, it lacks details like rate limits, authentication needs, or error conditions, leaving some behavioral aspects unclear.

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

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

The description is a single, efficient sentence that front-loads the core action and key details (target, method). There's no wasted wording, and it directly communicates the essential information without 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 mutation tool with no output schema and rich annotations, the description is minimally adequate. It covers the basic purpose and method but lacks context on usage scenarios, error handling, or return values. Given the complexity (6 parameters, creation operation), more completeness would be beneficial, but annotations provide some safety 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 parameters are fully documented in the schema. The description mentions 'base64-encoded content' and 'Linear issue', which aligns with schema details but doesn't add significant meaning beyond it. Baseline score of 3 is appropriate as the schema does the heavy lifting.

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

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

The description clearly states the action ('Create a new attachment') and target resource ('on a specific Linear issue'), with the specific method 'by uploading base64-encoded content'. It distinguishes from siblings like 'get_attachment' or 'delete_attachment' by specifying creation, though it doesn't explicitly contrast with other creation tools like 'create_document'.

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. It doesn't mention prerequisites (e.g., issue must exist), exclusions (e.g., file size limits), or compare with similar tools like 'create_document' for context. The description only states what it does, not when 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 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 cover the safety profile (non-readOnly, non-destructive, non-idempotent, non-openWorld), so the description doesn't need to repeat these. It adds no behavioral context beyond the basic creation action, such as rate limits, authentication needs, or what happens on duplicate names. No contradiction with annotations exists.

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

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

The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately understandable without unnecessary elaboration.

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 (6 parameters, creation operation) and lack of output schema, the description is minimally adequate. It states what the tool does but doesn't address behavioral nuances or usage context, leaving gaps that could hinder effective agent invocation without additional inference.

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 fully documents all parameters. The description adds no semantic details beyond the schema, such as explaining parameter interactions (e.g., 'teamId' omission for workspace labels) or constraints (e.g., color format specifics). Baseline 3 is appropriate given high schema 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 clearly states the action ('Create') and resource ('new Linear issue label'), making the purpose unambiguous. However, it doesn't differentiate this tool from sibling tools like 'list_issue_labels' or 'save_issue' beyond the obvious creation focus, missing explicit sibling distinction.

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

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

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing team access), exclusions (e.g., when not to create labels), or comparisons with related tools like 'list_issue_labels' for viewing existing labels.

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, readOnlyHint=false, and idempotentHint=false, which covers the safety profile. The description adds the specific resource being deleted (attachment) and the required parameter (ID), providing useful context beyond annotations. No contradictions exist.

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

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

The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it immediately scannable and appropriately sized for a simple operation.

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 destructive tool with good annotations but no output schema, the description is minimally adequate. It identifies the resource but lacks details about what deletion entails (e.g., permanent vs. recoverable, effects on linked resources) or what happens on success/failure.

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 the single parameter 'id' fully documented as 'Attachment ID'. The description mentions 'by ID' but adds no additional semantic context beyond what the schema provides, meeting the baseline for high schema 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 clearly states the action ('Delete') and resource ('attachment by ID'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'delete_comment' or explain what distinguishes an attachment from other resources in this system.

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 doesn't mention prerequisites (e.g., needing the attachment ID from get_attachment), consequences of deletion, or when deletion might be inappropriate compared to other operations.

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?

While annotations correctly mark this as destructive and non-idempotent, the description adds no context beyond the name. It fails to disclose that deletion is likely permanent (no recovery), that calling twice will error (non-idempotent), or what authorization is required to delete another user's comment.

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 of seven words that front-loads the action verb. No redundancy or filler content; every word is essential to understanding 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?

For a single-parameter destructive operation with complete schema annotations, the description is minimally adequate. However, given the destructive and non-idempotent nature (per annotations), it lacks critical behavioral context that would help an agent handle failures or confirm deletion intent.

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 met. The parameter 'id' is documented as 'Comment ID' in the schema, and the description adds no additional semantic value such as ID format (UUID), how to obtain it (from 'list_comments'), or that it must be an existing comment ID.

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 ('Delete') and resource ('comment') and adds context by specifying 'from a Linear issue,' which clearly identifies the domain. However, it does not explicitly distinguish from the sibling tool 'save_comment' (which likely updates/creates comments) or clarify when to use this versus 'list_comments'.

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

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

The description provides no guidance on when to use this tool versus alternatives like 'save_comment', nor does it mention prerequisites such as requiring admin permissions on the Linear issue or confirming the comment belongs to the correct issue before deletion.

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

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

Annotations already indicate this is a read-only, non-destructive, idempotent operation with a closed world. The description adds valuable context by specifying that it fetches images 'as viewable data' and mentions the source types (Linear issues, comments, documents), which helps the agent understand the tool's behavior 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 front-loaded with the core purpose in the first sentence, followed by usage context and output information. Every sentence adds value without redundancy, making it efficient and well-structured for quick comprehension.

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 parameter, no output schema) and rich annotations, the description is mostly complete. It covers purpose, usage, and output type. However, it could slightly improve by mentioning any limitations (e.g., image format support or size constraints) to be fully 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?

The input schema has 100% description coverage, fully documenting the single required parameter. The description adds minimal semantics beyond the schema by mentioning examples like 'issue description' and 'comment body', but does not provide additional details on format or constraints. This meets the baseline for high schema 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 clearly states the specific action ('extract and fetch images') and resource ('from markdown content'), with concrete examples of use cases ('screenshots, diagrams, or other images embedded in Linear issues, comments, or documents'). It distinguishes itself from sibling tools by focusing on image extraction rather than creation, deletion, or general data retrieval.

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 this tool ('to view screenshots, diagrams, or other images embedded in Linear issues, comments, or documents'), but does not explicitly state when not to use it or name specific alternatives. It implies usage for image extraction from markdown, which is sufficient but not exhaustive.

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 cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), so the description's burden is lower. It adds minimal context by specifying retrieval of 'content' (not just metadata), which is useful. However, it doesn't disclose rate limits, authentication needs, or error conditions, leaving some behavioral aspects unclear.

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, focused sentence with zero wasted words. It front-loads the core action ('Retrieve') and resource, making it immediately scannable and efficient. Every word earns its place without redundancy or ambiguity.

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 (single parameter, no output schema) and rich annotations, the description is minimally adequate. It covers the basic purpose but lacks details on output format (e.g., content type, size limits) or error handling. With annotations providing safety context, it's complete enough for simple use but could be more informative.

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 the single parameter 'id' fully documented in the schema. The description adds no additional meaning beyond implying the ID refers to an attachment, which is already clear from the tool name. This meets the baseline of 3 when the schema handles parameter documentation effectively.

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') and resource ('attachment's content'), making the purpose immediately understandable. It distinguishes from siblings like 'create_attachment' or 'delete_attachment' by focusing on retrieval. However, it doesn't explicitly differentiate from other 'get_' tools that might retrieve different resources, keeping it at a 4 rather than a perfect 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. It doesn't mention prerequisites (e.g., needing a valid attachment ID), exclusions, or comparisons to sibling tools like 'get_document' or 'extract_images'. The agent must infer usage from the name and context alone.

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 behavior. The description adds context by specifying the multiple identifier formats accepted, which goes 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?

Two concise sentences with front-loaded purpose and clear input formats, no extraneous information.

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

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

For a simple tool with one parameter and no output schema, the description covers purpose and input variations adequately, though it could briefly mention what 'high-level information' includes.

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 the description adds only the phrase 'high-level information' as output context, slightly extending meaning beyond the schema's parameter 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 retrieves high-level information about a Linear diff pull request and lists the accepted identifier formats, distinguishing it from sibling tools like list_diffs and get_diff_threads.

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

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

The description implies when to use the tool (when you have a diff identifier and want high-level info) but does not explicitly contrast with alternatives or state when not to use it.

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

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 safety profile is clear. The description adds the behavioral detail that the tool retrieves both general and anchored threads, which is consistent but not substantial 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?

Two sentences, no fluff, front-loaded with purpose. Every sentence adds value: first defines the tool, second gives a specific usage hint. Highly concise and 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 6 parameters and no output schema, the description is somewhat sparse. It explains the return type (top-level threads) but not pagination, filtering, or required input context. However, the schema covers these details, so the description is minimally adequate.

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

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

Input schema coverage is 100% with descriptions for all 6 parameters. The description only reiterates the threadId parameter's purpose ('Pass threadId to fetch one specific thread'), which is already stated in the schema. Thus, the description adds minimal 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 action ('retrieve'), the resource ('top-level diff comment threads'), and the scope ('including general threads and file/line anchored threads'). It also distinguishes from sibling tools like list_comments or list_diffs by specializing in diff threads.

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 specific guidance: 'Pass threadId to fetch one specific thread.' It implies the tool is for retrieving threads, but does not explicitly state when not to use it or compare with alternatives. However, the context of sibling tools makes the usage clear.

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

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

Annotations cover key traits (read-only, non-destructive, idempotent, closed-world), so the bar is lower. The description adds that retrieval can be by 'ID or slug', which is useful context beyond annotations. However, it doesn't disclose additional behaviors like error handling, rate limits, or authentication needs, leaving room for improvement.

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

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

The description is a single, efficient sentence with zero waste—it directly states the tool's purpose without fluff. It's appropriately sized for a simple retrieval tool and front-loaded with essential information, making it easy for an agent to parse quickly.

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 (one parameter, simple retrieval), rich annotations, and no output schema, the description is minimally adequate. It covers the basic action but lacks details on usage context, error cases, or return format, which could help an agent invoke it more effectively. It meets the minimum viable threshold.

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 the parameter 'id' fully documented in the schema. The description adds that 'id' can be a 'slug' as well, providing slight semantic clarification. Since the schema does most of the work, a baseline score of 3 is appropriate, with minimal extra value from 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 action ('Retrieve') and resource ('a Linear document'), specifying it's done 'by ID or slug'. It distinguishes from siblings like 'list_documents' (which lists multiple) and 'update_document' (which modifies), but doesn't explicitly contrast with other retrieval tools like 'get_attachment' or 'get_issue', keeping it at 4.

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. It doesn't mention prerequisites (e.g., needing a valid ID), exclusions, or compare to similar tools like 'list_documents' for browsing or 'search_documentation' for queries. The description only states what it does, not when to apply 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 this as read-only, non-destructive, and idempotent. The description adds valuable context about what specific data is included (attachments, git branch name) beyond just retrieving basic issue info. However, it doesn't mention rate limits, authentication needs, or error conditions.

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 that's front-loaded with the core purpose and efficiently lists the additional included data. Zero wasted words or redundant information.

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

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

For a read operation with comprehensive annotations and full schema coverage, the description provides good context about what data is returned. However, without an output schema, it could benefit from more detail about the return format structure. The description covers the essential purpose well given the tool's complexity.

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

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

Schema description coverage is 100%, so all parameters are documented in the schema. The description doesn't add any parameter-specific information beyond what's already in the schema descriptions. Baseline 3 is appropriate when schema does the heavy lifting.

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'), resource ('issue'), and scope ('detailed information including attachments and git branch name'). It distinguishes from siblings like list_issues (which lists multiple issues) and get_issue_status (which retrieves status 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 implies usage when detailed information about a specific issue is needed, but doesn't explicitly state when to use this vs. alternatives like list_issues or get_issue_status. No exclusions 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 cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), so the bar is lower. The description adds minimal context by specifying retrieval by 'name or ID', but doesn't disclose additional aspects like error handling, rate limits, or authentication needs. It doesn't contradict annotations, but adds limited value beyond 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, efficient sentence with zero waste—it directly states the purpose without fluff. It's appropriately sized and front-loaded, making it easy to parse quickly.

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 (3 required parameters) and rich annotations, the description is minimally adequate. However, with no output schema, it doesn't explain return values or format, and it lacks context on prerequisites or error cases. It meets basic needs but has clear gaps in 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 description coverage is 100%, with clear parameter descriptions in the schema. The description adds marginal value by mentioning retrieval 'by name or ID', implying parameters are used for lookup, but doesn't explain semantics beyond what the schema provides (e.g., how 'team' relates to 'id' and 'name'). Baseline 3 is appropriate given high schema 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 clearly states the verb 'retrieve' and resource 'detailed information about an issue status in Linear', specifying the action and target. However, it doesn't explicitly differentiate from sibling tools like 'get_issue' or 'list_issue_statuses', which would require mentioning scope or output format differences.

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' (which might include status) or 'list_issue_statuses' (which lists multiple statuses). It lacks explicit when-to-use or when-not-to-use instructions, leaving usage context implied at best.

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 cover key traits (read-only, non-destructive, idempotent, closed-world). The description adds no behavioral context beyond this, such as error handling, rate limits, or authentication needs. It doesn't contradict annotations, but provides minimal extra value.

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

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

The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and includes essential details (retrieval by ID or name) without unnecessary elaboration.

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 operation with good annotations and full schema coverage, the description is adequate but minimal. It lacks output details (no output schema exists) and doesn't address usage context or error cases, leaving some gaps in 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 description coverage is 100%, with clear parameter documentation. The description mentions 'ID or name' for the query parameter, but this is already in the schema. It adds no additional meaning or examples beyond what the structured data 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 action ('Retrieve details') and resource ('specific milestone'), specifying it works by 'ID or name'. However, it doesn't explicitly differentiate from sibling tools like 'list_milestones' or 'save_milestone', which would be needed for a perfect score.

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. It doesn't mention sibling tools like 'list_milestones' for browsing milestones or 'save_milestone' for updates, nor does it specify prerequisites or exclusions for 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 cover key traits (read-only, non-destructive, idempotent, closed-world), so the description doesn't need to repeat these. It adds minimal context by specifying 'details of a specific project', but doesn't disclose additional behaviors like error handling, rate limits, or authentication needs. No contradiction with annotations is present.

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

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

The description is a single, efficient sentence that front-loads the core purpose ('Retrieve details of a specific project'). It avoids redundancy but could be slightly more informative, such as by hinting at optional inclusions, though this isn't required given the schema coverage.

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 (4 parameters, no output schema) and rich annotations, the description is minimally adequate. It states what the tool does but lacks details on output format, error cases, or usage context, which could help an agent use it more effectively despite the annotations covering safety aspects.

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%, providing full details on all parameters (query, includeMembers, includeResources, includeMilestones). The description adds no parameter-specific information beyond implying a 'specific project' via the query, so it meets the baseline of 3 without compensating for gaps.

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 resource ('details of a specific project in Linear'), making the purpose understandable. However, it doesn't distinguish this tool from similar siblings like 'list_projects' or 'get_issue', which could also retrieve details but for different resources or scopes.

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 doesn't mention siblings like 'list_projects' for multiple projects or 'get_issue' for issues, nor does it specify prerequisites or contexts for usage, leaving the agent to infer based on tool names alone.

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, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds minimal context beyond this, stating it retrieves details but not elaborating on behavior like error handling or return 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, efficient sentence with zero waste. It's front-loaded with the core purpose and appropriately sized 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?

For a simple read operation with good annotations (readOnly, idempotent) and full schema coverage, the description is adequate but minimal. It lacks output details (no output schema) and doesn't address usage context, leaving some gaps in 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 description coverage is 100%, with the 'query' parameter documented as accepting 'Team UUID, key, or name'. The description doesn't add meaning beyond this, so it meets the baseline of 3 for high schema 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 clearly states the verb ('Retrieve') and resource ('details of a specific Linear team'), making the purpose unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'list_teams' or 'get_project', which would require 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?

No guidance is provided on when to use this tool versus alternatives like 'list_teams' or other 'get_' tools. The description implies it's for retrieving a specific team, but doesn't clarify prerequisites, exclusions, or comparison to siblings.

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 safety information (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the description doesn't need to repeat those. It adds the specific resource context ('Linear user') but doesn't disclose additional behavioral traits like error conditions, authentication needs, or rate limits beyond what annotations cover.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized and front-loaded with essential information.

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

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

Given the simple single-parameter input schema, comprehensive annotations covering safety aspects, and lack of output schema, the description is minimally adequate. However, it could better address usage context relative to sibling tools and provide more behavioral context beyond annotations.

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 description coverage is 100%, with the single parameter 'query' fully documented in the schema. The description doesn't add any meaningful parameter semantics beyond what the schema already provides, so it meets the baseline for high schema 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 clearly states the action ('Retrieve details') and target ('specific Linear user'), which is a specific verb+resource combination. However, it doesn't explicitly differentiate from the sibling 'list_users' tool, which appears to retrieve multiple users rather than a specific one.

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 'list_users' or other user-related operations. It lacks any context about prerequisites, appropriate scenarios, or exclusions.

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

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

Annotations already declare readOnlyHint=true, openWorldHint=false, idempotentHint=true, and destructiveHint=false, covering key behavioral traits. The description adds minimal context beyond this—it specifies the scope ('for a specific Linear issue') but doesn't mention pagination behavior, rate limits, or authentication needs. With annotations doing most of the work, the description provides some value but not rich behavioral disclosure.

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

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

The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part earns its place by specifying the action and target resource clearly, making it easy for an agent to parse quickly.

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 (4 parameters, 1 required), rich annotations, and 100% schema coverage, the description is minimally adequate. However, with no output schema, it doesn't explain return values (e.g., comment structure or pagination details), leaving gaps. It meets basic needs but lacks depth for full agent understanding.

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 each parameter well-documented in the schema (e.g., 'issueId' as 'Issue ID or identifier', 'limit' with default and max). The description adds no parameter semantics beyond what the schema provides, such as explaining the format of 'issueId' or how 'cursor' works. Baseline 3 is appropriate when the schema carries the full burden.

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 comments') and resource ('for a specific Linear issue'), which provides a specific verb+resource combination. However, it doesn't distinguish this tool from potential sibling tools like 'get_comment' or 'save_comment' that might exist in the broader Linear ecosystem, though those aren't in the provided sibling list.

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 doesn't mention prerequisites, when not to use it, or how it differs from other list tools like 'list_issues' or 'list_documents' in the sibling set. The agent must infer usage from the tool name alone.

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 cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), so the description's burden is lower. It adds context by specifying the team scope, but does not disclose additional details like rate limits, authentication needs, or return format. No contradiction with annotations exists.

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

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

The description is a single, efficient sentence that front-loads the core purpose without unnecessary details. It earns its place by clearly stating the action and scope, making it highly 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 low complexity (2 parameters, no output schema) and rich annotations, the description is mostly complete. It specifies the team context but could improve by hinting at return values or usage scenarios, though annotations mitigate gaps.

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

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

Schema description coverage is 100%, so the schema fully documents parameters (teamId and type with enum). The description adds no extra semantic meaning beyond implying team filtering, aligning with the baseline score when schema coverage is high.

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') and resource ('cycles for a specific Linear team'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'list_issues' or 'list_milestones' beyond the resource type, which prevents a perfect score.

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 other list_* tools for different resources or search functions. It mentions a specific team context but lacks explicit when/when-not instructions or named 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, destructiveHint, idempotentHint, and openWorldHint, so the safety profile is covered. However, the description adds no behavioral context beyond what annotations provide, such as pagination behavior, response structure, or execution constraints.

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, concise sentence that is front-loaded with the key action and resource. No unnecessary words; every part is meaningful.

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 is minimal. It does not explain return values, pagination behavior, or how filters interact. For a list tool with many options, more context is needed for effective use.

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% (all parameters documented in schema). The description adds no additional meaning beyond the schema, so per guidelines baseline of 3 is appropriate.

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

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

Description clearly states the verb 'List', the resource 'Linear diff pull requests', and scope 'visible to the authenticated user'. This effectively distinguishes it from siblings like 'get_diff' (single) or 'list_comments' (different resource).

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

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

Description lacks any guidance on when to use this tool versus alternatives. It does not mention prerequisites, context, or which filtering scenarios are appropriate, leaving the agent to infer usage from the name and 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 provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds no behavioral context beyond what annotations provide—no mention of pagination behavior (implied by 'cursor' parameter), rate limits, authentication requirements, or what constitutes a 'document' in Linear 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 a single, efficient sentence that states the core purpose without unnecessary words. However, it could be more front-loaded with key differentiators (like filtering capabilities) rather than just stating the basic action.

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 list operation with rich annotations and comprehensive schema coverage, the description is minimally adequate. However, without an output schema, the description should ideally mention what information is returned (document metadata vs full content) or pagination behavior. The current description leaves these aspects unspecified.

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, all 10 parameters are well-documented in the schema itself. The description adds no parameter semantics beyond what the schema provides—it doesn't explain relationships between parameters (e.g., how 'query' interacts with other filters) or provide usage examples. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the action ('List') and resource ('documents in the user's Linear workspace'), providing specific verb+resource. However, it doesn't distinguish this from sibling tools like 'list_issues' or 'list_projects' beyond the resource type, and doesn't mention filtering capabilities that differentiate it from 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 provides no guidance on when to use this tool versus alternatives. There's no mention of when to use 'list_documents' versus 'get_document' (for single document retrieval) or 'search_documentation' (for broader searches), nor any context about prerequisites or appropriate 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 cover safety (readOnlyHint=true, destructiveHint=false, idempotentHint=true), so the bar is lower. The description adds context about the scope ('workspace or team'), which isn't in annotations, but doesn't mention pagination behavior, rate limits, or authentication needs.

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

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

The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. Every part ('List available issue labels in a Linear workspace or team') contributes directly to understanding 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 low complexity (read-only list operation), rich annotations, and full schema coverage, the description is mostly complete. However, without an output schema, it could benefit from mentioning the return format (e.g., list of label objects) to fully guide the 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 description coverage is 100%, so the schema fully documents all 5 parameters. The description doesn't add any parameter-specific details beyond what's in the schema, meeting the baseline of 3 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 clearly states the verb ('List') and resource ('available issue labels'), specifies the scope ('in a Linear workspace or team'), and distinguishes it from siblings like 'list_project_labels' and 'list_issues' by focusing specifically on 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?

The description implies usage for retrieving issue labels but doesn't explicitly state when to use this tool versus alternatives like 'list_project_labels' or 'get_issue' (which might include label info). No guidance on prerequisites or exclusions 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?

Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds practical usage context about assignee values ('me' and 'null'), which is helpful but doesn't elaborate on rate limits, authentication needs, or pagination behavior beyond the cursor parameter in 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?

The description is extremely concise—two sentences with zero wasted words. It's front-loaded with the core purpose and immediately follows with practical usage notes, making it highly efficient and easy to parse.

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 16 parameters, 100% schema coverage, and annotations covering safety, the description is minimally adequate. It lacks output schema, so return values aren't described, but the annotations help. For a complex list tool, more behavioral context (e.g., pagination, default filters) would improve completeness, though the schema compensates somewhat.

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 fully documents all 16 parameters. The description adds minimal value by clarifying assignee semantics with 'me' and 'null', but doesn't provide additional context beyond what's already in the schema descriptions. This meets the baseline for high schema 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 clearly states the action ('List issues') and resource ('in the user's Linear workspace'), making the purpose immediately understandable. It doesn't explicitly distinguish from sibling list tools like list_comments or list_projects, but the resource specificity is adequate for basic 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 some usage guidance with the 'me' and 'null' examples for the assignee parameter, which helps clarify when to use specific values. However, it doesn't offer broader context about when to choose this tool over alternatives like get_issue or search_documentation, nor does it mention any prerequisites or exclusions.

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

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

Annotations cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), so the description doesn't need to repeat these. It adds some context by specifying the scope ('in a Linear team'), but doesn't elaborate on output format, pagination, or error handling, leaving room for improvement.

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

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

The description is a single, efficient sentence with no wasted words. It's front-loaded with the core purpose and avoids unnecessary elaboration, making it easy to parse quickly.

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 simple read-only nature (annotations cover safety), single parameter, and lack of output schema, the description is minimally adequate. However, it doesn't address potential complexities like what 'available issue statuses' includes (e.g., default vs. custom) or how results are structured, leaving gaps for an 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?

With 100% schema description coverage, the input schema fully documents the single required parameter ('team'). The description adds no additional parameter details beyond implying the team context, meeting the baseline for high schema coverage without 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 action ('List') and resource ('available issue statuses in a Linear team'), making the purpose understandable. However, it doesn't explicitly differentiate from the sibling tool 'get_issue_status' (which likely retrieves a single status), leaving some ambiguity about when to use 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?

The description provides no guidance on when to use this tool versus alternatives like 'get_issue_status' or other list tools. It lacks context about prerequisites (e.g., needing team access) or typical use cases, offering minimal usage direction beyond the basic purpose.

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 strong behavioral hints (readOnly, non-destructive, idempotent, closed-world), so the description adds minimal value. It doesn't disclose additional traits like pagination behavior, sorting, filtering capabilities, or rate limits. However, it doesn't contradict the annotations, maintaining consistency with the read-only nature implied by 'List'.

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

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

The description is a single, efficient sentence that directly states the tool's purpose with zero wasted words. It's appropriately sized for a simple list operation and front-loads the essential information without unnecessary elaboration.

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 (single required parameter), rich annotations covering safety and behavior, and lack of output schema, the description is minimally adequate. However, it doesn't address what the output contains (e.g., milestone fields, format) or how results are structured, which could be helpful despite annotations.

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 the single parameter 'project' documented as accepting 'name, ID, or slug'. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline for high schema coverage without compensating 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 action ('List all milestones') and resource ('in a Linear project'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'get_milestone' (singular) or 'list_cycles', but the verb+resource combination is specific enough for basic understanding.

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_milestone' (singular retrieval) or other list_* tools. There's no mention of prerequisites, context for selection, or exclusions, leaving the agent to infer usage purely from the tool name and description.

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 cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), so the description does not need to repeat these. It adds minimal context by specifying the workspace scope ('Linear workspace'), but does not disclose additional traits like rate limits, authentication needs, or pagination behavior beyond what the schema implies.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded with the core action and resource, making it easy to understand at a glance, and every part of the sentence contributes to clarity.

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 (a simple list operation), rich annotations (covering safety and behavior), and full parameter documentation, the description is adequate but minimal. It lacks output details (no output schema provided) and does not address sibling tool differentiation, which could help in more complex scenarios.

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

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

With 100% schema description coverage, the input schema fully documents all parameters (name, limit, cursor, orderBy), including defaults and constraints. The description adds no parameter-specific semantics beyond what the schema provides, so it meets the baseline score of 3 without compensating for any gaps.

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

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

The description clearly states the action ('List') and resource ('available project labels in the Linear workspace'), making the purpose evident. However, it does not explicitly differentiate this tool from its sibling 'list_issue_labels', which lists a different type of label, leaving room for potential confusion.

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 'list_issue_labels' or other list tools. It lacks context about prerequisites, such as needing a specific project or workspace access, and does not mention 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 indicate this is a read-only, non-destructive, idempotent operation with a closed-world scope. The description adds no behavioral context beyond this, such as pagination behavior (implied by the 'cursor' parameter but not explained), rate limits, or authentication requirements. It doesn't contradict annotations, but provides minimal additional value.

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 zero wasted words. It's front-loaded with the essential purpose and appropriately sized for a straightforward list operation with comprehensive schema documentation.

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 (14 parameters, no output schema) and rich annotations, the description is minimally adequate. It states what the tool does but lacks context about return format, pagination, error conditions, or relationship to sibling tools. The annotations cover safety aspects, but more operational guidance would be helpful.

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 input schema thoroughly documents all 14 parameters. The description adds no parameter-specific information beyond what's in the schema, so it meets the baseline expectation without providing extra semantic context about how parameters interact or typical usage patterns.

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

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

The description clearly states the action ('List') and resource ('projects in the user's Linear workspace'), making the purpose immediately understandable. However, it doesn't differentiate this tool from similar sibling tools like 'list_issues' or 'list_teams' beyond the resource type, which prevents a perfect score.

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_project' (for a single project) or 'list_issues' (for issues within projects). There's no mention of prerequisites, typical use cases, or when other tools 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?

Annotations already cover key behavioral traits (read-only, non-destructive, idempotent, closed-world), so the description adds minimal value. It does not disclose additional context like rate limits, authentication needs, or pagination behavior (implied by 'cursor' parameter but not explained). No contradiction with annotations exists.

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

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

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it easy for an agent to parse quickly.

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 (a read-only list operation), rich annotations, and full schema coverage, the description is adequate but minimal. It lacks output format details (no output schema) and sibling differentiation, which could help an agent use it more effectively in context with other tools.

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 all 7 parameters well-documented in the schema itself (e.g., 'limit' with default/max, 'orderBy' with enum values). The description adds no parameter-specific information beyond what the schema provides, so it meets the baseline of 3 for high schema 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 clearly states the action ('List') and resource ('teams in the user's Linear workspace'), making the purpose immediately understandable. However, it does not explicitly differentiate this tool from similar sibling tools like 'get_team' or 'list_projects', which would be needed for a score of 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_team' (for a single team) or other list tools. It lacks any context about prerequisites, typical use cases, or exclusions, leaving the agent to infer usage from the tool name alone.

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 strong behavioral hints (read-only, non-destructive, idempotent, closed-world). The description adds minimal context beyond this - it implies retrieval from a workspace context but doesn't mention pagination behavior (though cursor parameter suggests it), rate limits, authentication requirements, or what 'Linear workspace' specifically means. No contradiction with annotations exists, but the description doesn't significantly enhance behavioral understanding.

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

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

The description is a single, efficient sentence that immediately communicates the core function. There's zero wasted language or redundancy. It's appropriately sized for a straightforward listing tool and gets directly to the point without unnecessary elaboration.

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 rich annotations (covering safety and idempotency) and comprehensive schema documentation, the description provides adequate context for a read-only listing operation. However, without an output schema, the description doesn't indicate what user data is returned or in what format. For a tool with 5 parameters including pagination and filtering options, more context about result structure would be helpful despite the good annotation coverage.

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, all parameters are well-documented in the schema itself. The description adds no parameter-specific information beyond the generic 'Retrieve users' context. It doesn't explain relationships between parameters (e.g., how 'team' interacts with 'query') or provide usage examples. This meets the baseline for high schema coverage but doesn't add meaningful semantic 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 action ('Retrieve') and resource ('users in the Linear workspace'), making the purpose immediately understandable. However, it doesn't distinguish this tool from its sibling 'get_user' (singular), which appears to fetch a specific user rather than list multiple users. The description could be more specific about the listing/collection aspect.

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. With sibling tools like 'get_user' (singular) and 'list_teams', there's no indication whether this tool should be used for browsing all users versus fetching specific ones, or whether it's complementary to team-related queries. No explicit when/when-not instructions or alternative mentions are provided.

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

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

Annotations are all false, so description must fill in behavioral details. It explains that this tool returns an upload URL and headers, and that actual file upload occurs outside MCP. It also notes the signed URL expiration (60 seconds). However, it does not mention what server-side state is created (e.g., an upload request record). No contradiction with annotations (readOnlyHint=false aligns with write operation).

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

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

The description is moderately long but well-structured as a numbered workflow. The initial sentence states purpose, followed by steps and warnings. The curl example is detailed but helpful. Every sentence adds value, though it could be slightly more compact without the example. Overall, it is efficient and front-loaded.

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

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

The tool is part of a two-step upload process, and the description covers the entire workflow, including the external upload step and the follow-up tool call. It also mentions constraints and provides an example. However, it lacks error scenarios (e.g., what happens if the URL expires or upload fails). No output schema is provided, but the description explains the expected return (uploadRequest.url and headers).

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 all parameters have descriptions. The description adds workflow context by specifying which parameters are required (issue, filename, contentType, size) and implying that title and subtitle are optional. It also reinforces constraints. While the schema already provides good documentation, the description slightly enhances understanding by connecting parameters to the upload process.

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

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

The description clearly states the tool's purpose: 'Prepare a direct Linear file upload for an existing issue.' It differentiates from siblings by explicitly outlining the two-step workflow and naming the subsequent tool (create_attachment_from_upload).

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 (1. call this tool, 2. upload with PUT, 3. send headers verbatim, 4. call create_attachment_from_upload). Also warns about strict requirements like not base64-encoding, signed header exactness, and 60-second URL expiry. Clearly indicates when to use this tool and what to do next.

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 destructiveHint=true and readOnlyHint=false; the description adds valuable behavioral context about the upsert pattern (create vs update based on id presence) and conditional requirements, without contradicting the safety 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 tightly constructed sentences: purpose statement first, followed by conditional logic, then requirements. Zero redundancy, appropriate use of backticks for parameter references.

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 4-parameter upsert operation with destructive annotations but no output schema, the description adequately covers the primary behavioral contract (create vs update logic) and parameter requirements, though it omits failure modes or side effects.

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, baseline is 3. Description adds crucial semantic value by documenting that issueId is required when creating (business logic not captured in JSON schema required array) and explaining the id parameter's role in determining the operation mode.

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 states specific verbs ('Create or update') + resource ('comment on a Linear issue'), clearly distinguishing from sibling tools like delete_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?

Provides explicit conditional logic ('If id is provided, updates... otherwise creates') and clarifies requirements ('When creating, issueId and body are required'), though it does not explicitly name sibling alternatives like delete_comment.

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

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

Annotations already indicate `destructiveHint: true`, signaling mutation. The description adds detail: it clarifies create-or-update behavior, reparenting possibility, and required/optional fields. No contradiction with annotations (destructiveHint true is consistent with mutation). The description compensates for lack of readOnlyHint with explicit mutation disclosure.

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

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

Description is a single coherent paragraph with two sentences, each carrying substantial information. Every clause adds value: first sentence states create-or-update behavior; second covers creation requirements; third clarifies update reparenting. 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?

Given 7 parameters, 100% schema coverage, and no output schema, the description adequately explains the conditional logic and constraints. However, it does not mention the return value (e.g., what is returned on success), nor does it cover edge cases like what happens if both `project` and `issue` are provided during creation (it says exactly one must be specified, but not the error 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%, so the schema already documents each parameter. The description adds meaning beyond the schema by explaining conditional logic (e.g., `id` distinguishes create vs update, `project`/`issue` mutual exclusivity on creation, and reparenting on update). This provides valuable semantics not captured by individual 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?

Description clearly states the tool creates or updates a Linear document, differentiating between create and update behavior based on the presence of `id`. It specifies requirements for creation (`title` required, exactly one of `project` or `issue`) and update behavior (optional reparenting). This provides a specific verb+resource and effective differentiation from other save tools like `save_comment` or `save_issue`.

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

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

Description explicitly tells when to provide `id` (update) vs omit (create), and notes constraints on `project`/`issue`. However, it does not mention when an agent might prefer alternatives like `save_issue` or other sibling tools, nor does it say when NOT to use this tool (e.g., if only updating a single field without reparenting).

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 destructiveHint=true and readOnlyHint=false. Description adds value by explaining the upsert behavior and assignee polymorphism ('accepts user ID, name, email, or me'), but does not mention the append-only nature of relationship fields (links, blocks) described in 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?

Three tight sentences with zero waste. Front-loaded with create/update verb, conditional logic in second sentence, and parameter-specific note in third. Every sentence conveys unique semantic information not inferable from schema alone.

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?

Appropriate for 23-parameter tool with 100% schema coverage. Description covers the upsert contract, conditional validation rules, and polymorphic parameter handling. No output schema exists but description appropriately focuses on 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 has 100% coverage (baseline 3). Description adds critical semantic constraints: conditional requirements ('title and team are required when creating') and crucial field usage guidance (use `assignee` not `assigneeId`, polymorphic input formats). This compensates for schema's lack of conditional validation rules.

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 'Create or update a Linear issue' with explicit conditional logic (if id provided, updates; otherwise creates). This distinguishes it from sibling tools like get_issue (read-only) and specific 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?

Provides clear usage conditions: 'If `id` is provided, updates... otherwise creates' and prerequisites 'When creating, `title` and `team` are required'. Lacks explicit 'when not to use' alternatives but effectively guides the upsert decision pattern.

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 destructiveHint=true and readOnlyHint=false, establishing safety profile. Description adds valuable upsert behavioral context (create vs update branching logic) but omits details about partial vs full updates, side effects, or authentication 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?

Three tightly-written sentences with zero redundancy. Front-loaded with primary purpose, followed by conditional logic, then parameter requirement. Every sentence 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?

Adequate for a 5-parameter destructive upsert tool with no output schema. Covers the critical upsert contract and parameter constraints. Could benefit from noting what fields are preserved vs overwritten during updates, but completeness is solid given annotations handle safety signaling.

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?

Despite 100% schema coverage, the description adds synthesized semantic value by explaining the inter-parameter dependency: `id` triggers update mode, and `name` is conditionally required in create mode. This relational logic helps the agent construct valid requests.

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?

Excellent specificity: verbs 'Create or update', resource 'milestone in a Linear project', and clear upsert logic. Distinguishes from read-only siblings like get_milestone and list_milestones by describing mutation behavior.

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?

Clear conditional logic for when to provide `id` (update) vs omitting it (create), and conditional requirement for `name`. Lacks explicit guidance on when to prefer over alternatives like get_milestone for reads, but the upsert logic is well-documented.

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 destructiveHint=true and readOnlyHint=false, establishing the safety profile. The description adds the upsert behavioral logic (conditional create/update) but omits details on error conditions, conflict resolution, or data loss risks during updates.

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

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

Two sentences with zero waste: first establishes dual purpose and conditional behavior, second specifies validation rules. Perfectly front-loaded and appropriately sized for the tool's complexity.

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?

Complete for an 18-parameter upsert tool: covers the essential business logic (create vs update modes), key constraints, and leverages the comprehensive schema descriptions. Minor gap regarding output behavior or error scenarios, but sufficient given the structured schema coverage.

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 (baseline 3), the description adds critical business logic: it clarifies that id drives the create/update decision logic, and explicitly states which fields are conditionally required (name and team for creation) despite zero required parameters in the JSON schema.

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

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

Excellent specificity: 'Create or update a Linear project' provides clear verb+resource, and the description distinguishes from sibling read operations (get_project, list_projects) by explicitly stating the write intent.

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 conditional logic for mode selection (id presence determines update vs create) and explicit prerequisites for creation (name + team required). Lacks explicit guidance on when to prefer over other mutation tools or prerequisites like checking existence first.

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 strong behavioral hints (read-only, non-destructive, idempotent, closed-world). The description adds minimal context about what gets searched (documentation for learning) but doesn't disclose important behavioral details like rate limits, authentication needs, result format, or pagination behavior beyond what's in 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?

The description is a single, efficient sentence that gets straight to the point with zero wasted words. It's appropriately sized for a simple search tool and front-loads the essential 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?

For a search tool with good annotations but no output schema, the description is minimally adequate. It explains what gets searched but lacks details about result format, limitations, or error conditions. The annotations cover safety aspects, but more behavioral context would be helpful given the tool's purpose.

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 fully documents both parameters (query and page). The description doesn't add any meaningful parameter semantics beyond what the schema provides, such as query syntax examples or page size information. Baseline 3 is appropriate when schema does the heavy lifting.

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

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

The description clearly states the tool's purpose as searching Linear's documentation to learn about features and usage, which is a specific verb+resource combination. However, it doesn't distinguish this search tool from other search capabilities that might exist in the system, such as searching issues or projects, though no obvious sibling search tools are present in the provided list.

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 doesn't mention prerequisites, limitations, or when other tools might be more appropriate for finding information. The context is implied (learning about features and usage) but lacks explicit usage boundaries.

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