linear

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 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 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.