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

Annotations already indicate this is a write operation (readOnlyHint: false) and not idempotent, but the description adds no additional behavioral context. It does not disclose side effects, permission requirements, or whether adding an attachment might overwrite existing ones. The description simply restates the action without enriching the agent's understanding 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 a single, concise sentence with no wasted words. It is front-loaded with the core action. However, it is so terse that it sacrifices necessary detail, so it is efficient but not fully informative. This is acceptable as a concise structure but could be slightly expanded without losing 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 complexity (8 parameters, nested objects, output schema), the description is severely incomplete. It does not explain what an attachment is, the purpose of the required fields, or how the output schema relates to the result. An agent cannot confidently call this tool correctly based on the description alone. The lack of parameter semantics and usage context makes it nearly unusable.

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 0%, meaning the schema provides no parameter documentation. The description does not compensate by explaining any parameters, even the required ones (issueId, title, url). It only says 'add an attachment', leaving the agent to guess what each field means and how they are used. This is a critical gap for an 8-parameter tool with nested objects.

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 ('Add') and the resource ('attachment to an issue'), using a specific verb and resource. It is distinct from sibling tools like linear_getAttachments or linear_createCustomerNeedFromAttachment, so an agent can identify its purpose without ambiguity.

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

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

The description provides no guidance on when to use this tool versus alternatives. There is no mention of prerequisites, target use cases, or exclusions. An agent would have to infer when to add an attachment versus using other attachment-related tools. No context is given for when this is the appropriate choice.

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

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

The description does not add behavioral context beyond what annotations already provide (idempotentHint=true). It does not specify what happens if the label already exists, or any side effects.

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

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

A single sentence of 8 words, very concise and front-loaded. No wasted words, but could include more context without being verbose.

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

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

For a simple two-parameter operation with an output schema, the description is adequate but lacks details on label existence checks or duplicate handling. It is minimally complete.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds no extra meaning beyond the schema's parameter descriptions, which are already clear.

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 'Add a label to an issue in Linear' with a specific verb and resource. It distinguishes from the sibling tool 'linear_removeIssueLabel' which performs the opposite action.

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, nor does it mention prerequisites or conditions. The agent must infer usage from the tool name and sibling list.

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

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

The description adds no behavioral traits beyond what annotations already provide (readOnlyHint=false, destructiveHint=false, idempotentHint=true). It does not explain effects like idempotency or what 'add' entails operationally.

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 very concise with a single sentence, but it could be slightly more structured to include usage cues. No unnecessary words, but it trades completeness for brevity.

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, the description is adequate but lacks context about when adding to a cycle is appropriate or any side effects. The presence of an output schema reduces the need to describe return values, but the description remains minimal.

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

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

Schema coverage is 100%, so the description does not need to elaborate on parameters. The description adds no additional meaning beyond the schema field descriptions, which is acceptable but not improved.

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 'Add an issue to a cycle' uses a specific verb ('add') and clearly identifies the objects (issue and cycle). It distinguishes the tool from siblings like 'removeIssueFromCycle' and 'addIssueToProject' by specifying the target 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?

The description provides no guidance on when to use this tool versus alternatives such as 'removeIssueFromCycle' or 'addIssueToProject'. It does not mention any prerequisites or context 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 already provide idempotentHint=true and destructiveHint=false. The description adds no extra behavioral context (e.g., whether the issue must already exist, or what happens if it's already in the project).

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

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

The description is a single, concise sentence that conveys the purpose without unnecessary words.

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

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

Given the tool's simplicity, high schema coverage, and annotations, the description is fairly complete. However, it could mention that the issue must exist or the tool's idempotent nature, but these are covered by annotations and schema.

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

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

Both parameters have schema descriptions that adequately explain their purpose. The description does not add any additional meaning beyond the schema, so baseline score of 3 is appropriate.

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

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

Description clearly states the action 'Add an existing issue to a project', specifying both the verb and the resources involved. It effectively distinguishes from sibling tools like 'linear_removeIssueFromProject'.

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

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

No guidance on when to use this tool versus alternatives (e.g., when to add an issue to a project vs. to a cycle or release). No mention of prerequisites or context.

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

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

Annotations already provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds no additional behavioral context such as required permissions, whether duplicates are prevented, 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?

The description is a single, short sentence that conveys the core functionality without any unnecessary words. It is appropriately front-loaded.

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

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

For a simple tool with two required parameters and an output schema, the description sufficiently explains the purpose. Minor gaps exist in error handling or prerequisites, but overall it is complete enough for standard usage.

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

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

Schema description coverage is 100%, so the parameters are already documented. The tool description adds no further meaning to the parameters beyond what the schema provides, which meets the baseline.

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 'Add' and the resources 'issue to a release', making the action unambiguous. It distinguishes well from siblings like 'removeIssueFromRelease'.

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

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

No guidance on when to use this tool versus alternatives like 'addIssueToProject' or 'addIssueToCycle'. No preconditions or side effects mentioned.

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

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

Annotations already provide idempotentHint=true and destructiveHint=false. The description adds no behavioral details beyond the annotation, such as side effects or authorization needs. It does not contradict annotations, but adds minimal 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 sentence with under 10 words, front-loading the key action and object. No unnecessary 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 full schema coverage and an output schema, the description sufficiently covers the core action. Minor gap: does not mention handling of duplicate additions, but the idempotentHint annotation implies it's safe.

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

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

Schema coverage is 100% with clear parameter descriptions. The description adds no additional meaning beyond what the schema already provides, so baseline score of 3 is appropriate.

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

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

The description 'Add a member to a project' uses a specific verb ('Add') and resource ('member to a project'), clearly differentiating from sibling tools like removeProjectMember or addUserToTeam.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., addUserToTeam) or any prerequisites such as valid projectId or userId. The description lacks context for appropriate usage.

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

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

Annotations already declare idempotentHint: true and destructiveHint: false, so the description adds no extra behavioral context. It does not describe any side effects, authorization needs, or other behavioral traits beyond what is already structured.

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

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

The description is a single sentence without any superfluous information. It is front-loaded and efficient.

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 and the presence of annotations and an output schema, the description is adequate but lacks context about prerequisites or effects. It does not explain what 'add' entails (e.g., linking an existing project) or usage constraints.

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

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

Schema coverage is 100%, with both parameters having descriptions in the schema. The description does not add any additional meaning or clarification beyond the schema, meeting the baseline.

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 'Add a project to an initiative' uses a specific verb and resource, clearly distinguishing it from sibling tools like 'removeProjectFromInitiative' and 'getInitiativeProjects'. It leaves no ambiguity about the action.

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. There is no mention of prerequisites (e.g., that the initiative and project must already exist) or context to help the agent decide.

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 idempotent and non-destructive behavior. The description adds no extra behavioral context beyond what annotations provide, but does not contradict them.

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

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

The description is a single sentence with no wasted words. It is front-loaded with the action and object.

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 single-parameter tool with output schema and informative annotations, the description provides necessary context. No gaps identified.

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. The description only restates the schema's parameter description without adding new meaning.

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

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

The description clearly states the verb 'add' and resource 'entity to Linear favorites', distinguishing it from the sibling tool 'linear_removeFromFavorites'.

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

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

No guidance on when to use this tool versus alternatives like 'linear_removeFromFavorites' or other mutation tools. The description is purely declarative.

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 idempotentHint=true and destructiveHint=false. The description adds no behavioral context beyond that, such as what happens if the user is already on the team or required permissions.

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

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

One sentence, no waste. Could benefit from additional context (e.g., idempotency), but conveys the core action succinctly.

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 output schema and annotations, the description is minimally adequate but lacks context about idempotency and what happens with duplicates. For a tool with many siblings, more detail would help.

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

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

Schema coverage is 100%, so the schema already documents all parameters. The description does not add 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 uses a clear verb ('Add') and resource ('a user to a team'), which distinguishes it from sibling tools like linear_removeUserFromTeam and linear_updateTeamMembership.

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

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

No guidance on when to use this tool vs alternatives (e.g., updateTeamMembership). Does not mention idempotency or prerequisites like user not already being a member.

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 and idempotentHint=true. The description 'Archive a customer need' is consistent but adds no additional behavioral context beyond what annotations provide, such as reversibility or side effects.

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 at four words, with no wasted text. It is frontloaded and easy to parse, though it could benefit from a slightly more structured form to include key details.

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 destructive nature and the existence of an output schema, the description is too minimal. It does not explain what archiving entails (e.g., whether it is reversible, effects on visibility) or provide context on when to archive, making it incomplete for a safe and effective tool 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?

There is only one parameter 'id' with a basic description in the schema. Schema coverage is 100%, so the description does not need to add extra semantics, but it also does not provide any additional context beyond the schema.

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

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

The description clearly states the verb 'Archive' and the resource 'customer need', making the purpose evident. However, it does not distinguish from similar sibling tools like 'linear_archiveRoadmap' or 'linear_archiveMilestone', hence a 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?

The description provides no guidance on when to use this tool versus alternatives. It does not mention any prerequisites, conditions, or context for archiving a customer need, leaving the agent without direction.

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

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

Annotations indicate destructiveHint=true and idempotentHint=true. The description uses 'Archive (trash)' which aligns with destructive behavior but does not elaborate on reversibility or side effects. It adds minimal value 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?

A single, concise sentence that effectively communicates the tool's purpose without unnecessary words or structure.

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 archive operation with one parameter and an output schema, the description covers the essential purpose. However, it lacks context about what happens to the document after archiving or how to reverse it, but the presence of an output schema mitigates this need 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?

Only one parameter 'id' with schema coverage 100%. The description merely repeats the schema's parameter description ('ID of the document to archive'), adding no additional meaning. Baseline score of 3 applies.

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

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

The description clearly states the verb 'Archive (trash)' and the resource 'a Linear document', which distinguishes it from sibling archive tools for other resources like roadmap, milestone, project, etc.

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

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

No guidance on when to use this tool versus alternatives, such as when to archive vs delete or unarchive. The description only states the action without context for decision-making.

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

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

Annotations indicate destructiveHint=true and idempotentHint=true, but the description adds no behavioral context beyond the action name. It fails to explain consequences like reversibility or impact on related entities.

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?

While short, the description is under-specified. Conciseness should not come at the expense of completeness; valuable context is missing.

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 destructive nature and presence of an output schema, the description should explain the archive effect, return value, and any prerequisites. It fails to do so.

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 no extra meaning to the single parameter. Baseline score of 3 is appropriate.

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

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

The description is a tautology: 'Archive an initiative' restates the tool's name without adding any specifics about what archiving entails or how it differs from other archive tools.

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

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

No guidance is provided on when to use this tool versus alternatives like linear_archiveProject or linear_archiveRoadmap. The user must infer context from the 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 declare idempotentHint=true and destructiveHint=true, indicating a safe-to-rearchive destructive action. The description adds no further behavioral details (e.g., reversibility, visibility changes). While consistent with annotations, it fails to clarify operational nuances beyond what the annotations provide.

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

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

The description is a single short sentence with no extraneous information. It is efficient but could benefit from a brief note on the effect of archiving. Nevertheless, it is appropriately concise for a simple tool.

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

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

Given the tool's simplicity (one param, output schema exists) and annotations providing safety traits, the description is partially complete. However, it omits what happens to the archived update (e.g., hidden vs deleted, ability to unarchive) which a sufficiently intelligent agent might need to know. The presence of an output schema mitigates the need to describe return values, but the overall behavioral context remains thin.

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

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

The input schema fully describes the only parameter (id) with the description 'ID of the initiative update to archive'. With 100% schema description coverage, the tool description adds no additional value for parameter semantics. Baseline score of 3 is appropriate.

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

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

The description 'Archive an initiative update' clearly states the verb (archive) and resource (initiative update). It distinguishes from sibling tools like linear_archiveInitiative and linear_archiveProjectUpdate due to the specific resource name. However, it does not elaborate on what archiving entails (e.g., hiding vs deleting), but the core purpose is clear.

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 linear_archiveProjectUpdate or linear_archiveInitiative. An agent must infer usage solely from the tool name and context, which increases selection risk.

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

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

The description adds no behavioral context beyond the annotations. While annotations already indicate destructiveHint=true and idempotentHint=true, the description does not elaborate on side effects, permissions, or irreversibility.

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 at three words, with no fluff. It is front-loaded but would benefit from a bit more detail without becoming verbose.

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

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

Given the presence of an output schema and full parameter documentation, the description is minimally adequate. However, it lacks usage context and behavioral details that would make it fully self-contained.

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

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

Schema coverage is 100% with one parameter well-documented in the schema. The description adds no additional meaning to the parameter, so baseline 3 is appropriate.

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

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

The description 'Archive an issue' clearly states the verb (archive) and the resource (issue), which is specific and distinguishes from sibling tools that archive different entities like projects or milestones.

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

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

No guidance is provided on when to use this tool versus alternatives (e.g., deleting an issue, or other archive tools). The description only states the action without context for appropriate usage.

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

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

Annotations already indicate destructiveness and idempotency. The description adds key context: the ownership requirement ('owned by the calling OAuth application') and what the tool does not do ('does not revoke an unrelated authorized application'), surpassing annotation content.

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 no unnecessary words. Every sentence adds value.

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

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

While an output schema exists, the description lacks details about reversibility (e.g., can it be unarchived?) and what happens to the app's own tokens. These gaps reduce completeness for a destructive tool.

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

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

The schema has 0% coverage for the sole parameter 'id'. The description compensates by clarifying that the ID must be an alpha child OAuth application owned by the caller, adding meaningful ownership and type constraints 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 states the specific action (archive), resource (alpha child OAuth application), and ownership constraint. It distinguishes from other archive tools with the resource type and includes a clarifying note about not revoking unrelated authorized applications.

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 archiving a managed OAuth application, but does not explicitly guide when to use this over alternatives like updating or deleting. It provides no direct comparison with sibling tools.

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

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

Annotations already provide idempotentHint=true and destructiveHint=true. The description adds no behavioral details beyond restating the action. It does not explain side effects, reversibility, or permissions, which would add 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, complete sentence with no unnecessary words. It is front-loaded and efficient.

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, output schema exists), the description is mostly adequate. However, it omits context about whether archiving is reversible or affects milestone items. Still, for a basic archive action, it covers the essential 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 coverage is 100% for the single parameter 'id', whose description is already in the schema. The tool description adds no additional semantic context, so baseline 3 is appropriate.

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

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

The description 'Archive a project milestone' clearly states the verb (archive) and resource (project milestone). It effectively distinguishes from sibling tools like linear_archiveRoadmap or linear_archiveProject by specifying the entity type.

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 context: use this tool when you want to archive a milestone. No exclusions or alternatives are mentioned, but given the clear entity type and sibling tools for other entities, the when-to-use is obvious.

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, readOnlyHint=false, and idempotentHint=true, so the safety profile is known. However, the description adds no additional behavioral context (e.g., impact on related data, reversibility constraints) beyond the annotations. With annotations present, the bar is lower, but the description contributes nothing extra.

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, direct sentence with no fluff. It is appropriately sized for a straightforward action, though it is minimal to the point of lacking helpful context.

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 destructive operation with a single required parameter and annotations covering safety, the description is minimally adequate. However, it omits any usage context (e.g., when to archive versus delete) and any description of the expected outcome, which could leave an agent uncertain about consequences.

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

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

Schema coverage is 100% with a single parameter (projectId) described as 'ID of the project to archive'. The description adds no new meaning beyond the schema, so it meets the baseline for high schema coverage. No elaboration on format or constraints is provided.

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

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

The description states a specific verb ('Archive') and a resource ('project'), making the core action clear. However, it does not differentiate from sibling archive tools like linear_archiveDocument or linear_archiveTeam, relying on the name for 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?

No guidance is provided on when to use this tool versus alternatives (e.g., linear_unarchiveProject, linear_updateProject). The description simply states what it does without any context about prerequisites, side effects, or conditions for archiving.

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 already indicate destructiveHint=true and idempotentHint=true, the description adds no extra behavioral context. It does not explain what archiving entails (e.g., reversible, hides from views) or mention any side effects beyond what annotations provide.

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

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

The description is a single, efficient sentence with no extraneous information. It is front-loaded and concise, earning a perfect score for brevity.

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

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

Given that annotations and output schema exist, the description covers the essential action. However, it lacks completeness by not mentioning that the project update must exist, what happens on success, or any resulting state changes, which would be helpful for a simple operation.

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

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

The input schema has 100% coverage with a description for the single required parameter 'id' ('ID of the project update to archive'). The description does not add semantic value beyond the schema, meeting the baseline of 3.

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

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

The description 'Archive a Linear project update' uses a specific verb ('archive') and clearly identifies the resource ('project update'). It is distinct from sibling tools like unarchiveProjectUpdate or deleteProjectUpdate, making purpose unambiguous.

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

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

The description provides no guidance on when to use this tool versus alternatives such as unarchiveProjectUpdate or deleteProjectUpdate. No context is given about prerequisites or decision criteria, leaving the agent without direction.

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 and idempotentHint: true, covering key behavioral traits. The description adds no additional behavioral context (e.g., whether archiving is reversible or its side effects). While there is no contradiction, the description adds minimal value beyond annotations.

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

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

The description is three words long and immediately communicates the action and target. Every word is essential, and there is no extraneous information. This is a model of conciseness.

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

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

Given the tool's simplicity, annotations, and output schema, the description is minimally adequate. However, it could be improved by noting that archiving is likely reversible (sibling unarchiveRelease exists) or clarifying any effects on associated items. The agent may need to infer such details.

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 schema already explains the single parameter releaseId as 'The ID of the release to archive'. The description does not add any further semantic meaning, so a baseline score of 3 is appropriate.

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

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

The description 'Archive a release' clearly states the verb ('archive') and the resource ('release'). It effectively distinguishes the tool from siblings like linear_archiveRoadmap, linear_archiveMilestone, etc., which target different entities.

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 usage guidelines are provided. The description does not specify when to use this tool versus alternatives (e.g., unarchiveRelease, deleteRelease) or any prerequisites. This lack of guidance may confuse an AI agent.

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

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

Annotations already indicate destructiveHint=true, so the destructive nature is known. The description adds no further behavioral context (e.g., reversibility, side effects). With annotations, a 3 is appropriate.

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

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

The description is very short and to the point. It could be slightly more informative, but it is not verbose. A concise statement that efficiently conveys the core 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 simple destructive action, the description is minimally adequate. However, it lacks context about reversibility or impact, and given the availability of an output schema, a bit more description would improve completeness.

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

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

Schema coverage is 100% and the parameter description is already clear in the schema. The tool description does not add additional meaning beyond the schema, so baseline 3.

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

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

The description clearly states the action ('Archive') and the resource ('a release pipeline'). It is specific enough to distinguish from other archive tools (e.g., archiveRoadmap) by naming the resource type.

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

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

No guidance on when to use this tool versus alternatives like unarchiveReleasePipeline or deleteReleasePipeline. The description does not provide context 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 indicate destructiveHint=true, but description adds no extra behavior beyond the word 'archive'. Does not mention reversibility or impact on related data.

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?

Extremely concise (3 words) with no filler; could slightly benefit from more context but remains efficient.

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 tool with one parameter and existing annotations, the description is adequate but lacks mention of whether archiving is reversible or its effect on releases.

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 does not add further meaning to the stageId parameter beyond what the schema already provides.

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

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

Description clearly states the action ('archive') and resource ('release stage'), distinguishing it from sibling tools like archiveRelease and unarchiveReleaseStage.

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

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

No explicit guidance on when to use this tool versus alternatives like unarchiveReleaseStage; usage is implied but not articulated.

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 mark the operation as destructive and idempotent; the description adds no behavioral context beyond the word 'archive.' It does not explain whether the roadmap is hidden from lists, irreversible, or how duplicate archives are handled, and there is no annotation contradiction.

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

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

The description is three words with zero filler, front-loaded with the action and object. It is the minimal concise form appropriate for a one-parameter archive 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?

The tool is simple and structured data covers the parameter, output schema, and safety hints, but the description alone leaves the real-world effect of 'archive' unspecified. An agent would benefit from knowing that archived roadmaps are typically hidden and restorable via linear_unarchiveRoadmap; that context is absent.

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

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

The single parameter roadmapId is fully documented in the schema, so the description need not add much. It provides no additional guidance (e.g., where to find the ID), but the schema already supplies the meaning, matching the 100% coverage baseline.

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 ('Archive') and resource ('a roadmap'), unambiguously identifying the operation. It distinguishes cleanly from sibling tools like linear_getRoadmaps, linear_updateRoadmap, and linear_unarchiveRoadmap by naming the exact action and object.

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 gives no guidance on when to use this tool versus alternatives. It does not mention that archived roadmaps can be restored with linear_unarchiveRoadmap or contrast with linear_updateRoadmap, so an agent is left to infer selection criteria.

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

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

Annotations already indicate destructiveHint=true and idempotentHint=true. The description adds no additional behavioral context (e.g., what archiving entails, whether it can be undone).

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?

Extremely concise at one sentence, front-loaded with the core action. No wasted words.

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

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

For a destructive mutation tool with an output schema, the description is too sparse. It lacks context about effects on related entities or prerequisites.

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

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

Schema coverage is 100% with a clear description for the 'id' parameter. The tool description adds no extra 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 'Archive a team' uses a specific verb and resource. It is clear but does not differentiate from sibling archive tools like linear_archiveProject or linear_archiveDocument.

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

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

No guidance on when to use this tool versus alternatives (e.g., linear_archiveProject) or conditions under which it should be used. The description is too brief.

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 and idempotentHint=true, which the description does not expand upon. The description merely restates the operation without adding behavioral context (e.g., what archiving means for the template, whether it can be reversed).

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

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

The description is a single, concise sentence with no wasted words. It is front-loaded with the action and target, making it easily scannable.

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 input (one required param) and existence of an output schema, the description is adequate. It could mention the idempotent nature or typical effects of archiving, but is not critically incomplete.

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 fully describes the 'id' parameter ('ID of the template to archive'). The tool description does not add any additional meaning, meeting the baseline for high coverage.

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

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

The description 'Archive an issue template' uses a specific verb ('archive') and clearly identifies the resource ('issue template'). It effectively distinguishes this tool from sibling tools like 'linear_archiveRoadmap' or 'linear_archiveMilestone' by specifying the target 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?

The description provides no guidance on when to use this tool versus alternatives, no prerequisites, and no consequences. For a destructive action, such context is important but entirely missing.

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=false, destructiveHint=false, and idempotentHint=true, covering the mutation and idempotency aspects. The description adds no extra behavioral context, such as that assignment overrides the current assignee or any side effects. It does not contradict the annotations, but it also does not go beyond them, so a 3 is appropriate.

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

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

The description is a single, direct sentence with no wasted words. It is front-loaded with the action and objects, 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?

For a simple two-parameter action, the description provides the essential purpose, and the schema handles parameter details. However, it omits any mention of prerequisites (e.g., issue existence, user membership) or the fact that it replaces the current assignee. Since an output schema exists, this is not fully inadequate but leaves some 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?

The schema covers 100% of the parameters with clear descriptions, including the null option for unassigning. The description adds no additional meaning beyond what is already in the schema. Baseline 3 is assigned since 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 states a clear action (assign), the resource (issue), and the target (user). It is specific and not a tautology. However, it does not explicitly differentiate from sibling tools like linear_updateIssue, which might also change assignment, so it loses a point for lacking that discrimination.

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 vs. alternatives. The description does not mention that this is the dedicated tool for assignment or that other tools (e.g., linear_updateIssue) should be used for other issue modifications. It leaves the selection entirely to the agent's inference.

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?

Beyond stating the action, the description discloses no behavioral traits. It does not explain what happens when a cycle is completed (e.g., status change, effects on issues), nor any required permissions or side effects. Annotations provide idempotentHint but no operational 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 sentence of four words, highly concise and front-loaded. However, it omits important details that could be included without sacrificing conciseness, slightly reducing its value.

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

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

Given the tool is a mutation with one parameter and an output schema, the description is overly minimal. It lacks context about the outcome, prerequisites, and how it fits among cycle-related siblings. The agent would need additional knowledge to use it correctly.

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

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

Schema coverage is 100%, so the schema already describes the 'id' parameter. The description adds no additional semantics about the id (e.g., format, scope) beyond what is in the schema, meeting the baseline expectation.

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 'Mark a cycle as complete' clearly states the action (mark as complete) and the resource (cycle). It distinguishes this tool from sibling tools like linear_createCycle or linear_updateCycle, which have different purposes.

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

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

The description provides no guidance on when to use this tool versus alternatives, no prerequisites (e.g., cycle must be active), and no indication of when completion is appropriate. The agent has no context to decide between this and updateCycle.

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 idempotentHint=true and destructiveHint=false, so the description's behavioral disclosure is supplementary. It adds value by specifying the precondition (pipeline stage must be configured), which is not captured by annotations. No contradictions with annotations.

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

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

Two concise sentences: first states the action, second provides a critical precondition. No filler or redundant information. Perfectly front-loaded and efficient.

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 100% schema coverage and existence of output schema, the description is complete enough. It conveys the core action, precondition, and pairs well with annotations. For a non-destructive, idempotent mutation tool, no additional context is needed.

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

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

Input schema has 100% coverage with descriptions for both parameters (version optional defaulting to latest, pipelineId required). The description adds no additional semantic meaning beyond the schema, so it achieves the baseline score without extra clarification.

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 'Mark as completed' and the resource 'release', specifying the action and context. It also adds a precondition about the pipeline stage, which further clarifies the exact functionality and distinguishes it from other release-related tools like archive or update.

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

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

The description provides clear usage context by requiring the pipeline to have a completed release stage configured. However, it does not explicitly mention when not to use this tool or name alternative tools for related actions (e.g., updating release status via updateRelease), missing the opportunity to guide selection among 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 convey that this is a mutation (readOnlyHint=false), idempotent, and non-destructive. The description adds no additional behavioral context beyond the action itself, such as side effects on issue relationships or project membership, but it does not contradict the annotations. Given the annotations cover the basic safety profile, a 3 is appropriate.

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

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

The description is a single, efficient sentence with zero redundancy, directly stating the tool's purpose. It is front-loaded and contains no filler, making it an excellent example of conciseness.

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

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

For a tool with only two required parameters, clear schema descriptions, and an output schema, the minimal description is arguably sufficient for an agent to understand the core operation. However, it omits any mention of potential side effects (e.g., changes to the issue's hierarchy, position in project) or prerequisites, which could be important for a mutation. Thus, it is adequate but not 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, with clear parameter descriptions like 'ID or identifier of the issue to convert (e.g., ABC-123)'. The description adds no extra parameter meaning, so with high schema coverage the baseline of 3 is justified.

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

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

The description clearly states the specific verb 'convert' and the resource 'issue to a subtask', which is unambiguous and distinct from sibling tools like linear_transferIssue or linear_duplicateIssue. However, it does not explicitly reference alternatives or provide additional differentiation, so it is clear but not exhaustive.

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, no conditions for use, and no exclusions. It simply states the action without any contextual direction, leaving the agent without explicit routing information.

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

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

Annotations are all false (no readOnlyHint, no idempotency, no destructiveness), providing no safety profile. The description carries the burden but adds no behavioral detail: it does not mention that a comment is persistently created, that permissions may be required, or that notifications could fire. It only restates the action without consequences or side effects. This is a minimal disclosure for a 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 a single sentence, front-loaded with the action verb, and lists all valid target types efficiently. There is no redundant phrasing or empty filler. Every word contributes to the core purpose.

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

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

With 11 parameters and multiple optional target IDs, the description is critically incomplete. It never states that exactly one target identifier (issueId, projectId, etc.) or parentId is required, nor does it clarify which combinations are invalid. An agent could easily omit a target or provide multiple, leading to errors. The output schema exists but does not compensate for this missing invocation rule.

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 11 parameters are documented. The description adds value by enumerating the target resource types (issue, project, etc.), which clarifies which ID parameter to use, but it does not explain selection rules (e.g., exactly one target must be provided) or how parameters interact. This is baseline-level contribution given the schema already describes each parameter.

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 'Add a comment to' followed by a list of valid target resources (issue, project, initiative, update, document content, threaded reply). This is a specific verb+resource pattern that distinguishes it from sibling tools like linear_updateComment and linear_deleteComment. The purpose is unambiguous and immediately understood.

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 context (use this to create a comment), but it does not explicitly mention alternatives or when not to use it. It does not point to linear_updateComment or linear_deleteComment for editing/deleting. Since the verb 'Add' inherently separates creation from modification, the guidance is only implied, not explicit.

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 (all false) offer no behavioral cues. The description only states 'Create a customer', which implies mutation but provides no further details about side effects (e.g., audit logs, webhook triggers) or required permissions. It adds minimal value beyond the tool name.

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

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

The description is extremely concise at three words, with no fluff. However, it lacks structured information such as typical usage scenarios. While brevity is positive, the minimalism sacrifices completeness.

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 has 11 parameters and an output schema, the description is insufficient. It does not explain the creation flow, return value, or any constraints (e.g., required fields beyond 'name'). The agent must rely entirely on schema and tool name for context.

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

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

The input schema covers all 11 parameters with descriptions (100% coverage). The description does not add any extra meaning or clarify parameter relationships. Since schema coverage is high, the baseline score of 3 is appropriate.

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

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

The description 'Create a customer' clearly identifies the verb (create) and the resource (customer). It distinguishes from sibling tools like linear_updateCustomer or linear_getCustomers. However, it does not elaborate on what 'customer' means in the Linear context, which could cause ambiguity.

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

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

No guidance is given on when to use this tool versus alternatives such as linear_createCustomerNeed or linear_createIssue. The description does not mention prerequisites, contexts, or exclusions, leaving the agent to infer 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 are neutral (no readOnly, destructive, or idempotent hints). The description does not disclose that this is a write operation requiring authentication, potential side effects, or failure conditions (e.g., missing linked resource).

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

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

A single, front-loaded sentence efficiently conveys the core purpose. However, it could be slightly more structured with explicit parameter groupings.

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 an output schema, the description lacks context about which parameters are typically required, the meaning of priority values, and how to interpret the return value. It is too brief for a creation tool with 10 optional parameters.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema, only implying that at least one of issueId or projectId might be needed.

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 (customer need) and specifies the linkage to an issue or project, distinguishing it from sibling tools like get, delete, or update customer needs.

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

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

No guidance on when to use this tool vs alternatives like createCustomerNeedFromAttachment, nor any prerequisites or exclusions. The description only states the basic action.

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

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

Annotations indicate readOnlyHint=false and destructiveHint=false, but the description adds little behavioral detail. It says 'create or unarchive' but doesn't clarify idempotency (e.g., what happens if the need already exists and is not archived?), error states, or side effects such as whether the attachment is consumed or modified. The output schema exists but doesn't mitigate the lack of behavioral context.

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

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

The description is a single sentence with no fluff. It is concise but could benefit from an additional sentence for clarity without losing brevity. The structure is front-loaded with the key action, making it easy to scan.

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

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

Given the tool's complexity (create/unarchive, attachment integration) and 4 parameters, the description is insufficient. It lacks details about the unarchive behavior, required permissions, return format (though output schema exists), and relationships with sibling tools. The high schema coverage and output schema partially compensate, but the description still feels incomplete for an agent to confidently invoke.

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

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

All 4 parameters have descriptions in the schema, so baseline is 3. The description adds no extra meaning beyond what the schema provides. It doesn't explain the relationship between customerId and customerExternalId, nor the priority scale's exact meaning. Thus, no additional value, so score stays at 3.

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

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

The description specifies the verb 'create or unarchive', the resource 'customer need', and the source 'from an existing attachment'. It distinguishes from siblings like linear_createCustomerNeed (which likely creates from scratch) and linear_unarchiveCustomerNeed (which only unarchives). However, the 'unarchive' aspect could be clarified: it implies unarchiving if a need already exists for that attachment but doesn't fully explain the condition.

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

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

No explicit guidance on when to use this tool versus alternatives. Siblings like linear_createCustomerNeed, linear_unarchiveCustomerNeed exist, but the description does not mention when one is preferred over the other. The implied usage is when you have an attachment and want to associate a customer need, but no exclusions or prerequisites are stated.

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

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

Annotations indicate this is a mutation (readOnlyHint=false) but not destructive (destructiveHint=false). The description adds no behavioral context beyond what annotations imply, such as side effects, required permissions, or whether it can be undone.

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 brief (4 words) but fails to be informative. It lacks any structure or additional details that would help an agent use the tool effectively. Conciseness should not come at the cost of completeness.

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 has 6 parameters, an output schema, and many sibling tools, the description is too minimal. It does not explain the purpose of the cycle creation context, expected outcomes, or relationship to other cycle 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?

The schema covers 100% of parameters with descriptions, so the tool description does not need to add parameter meaning. It neither adds nor detracts from the schema, earning a baseline score of 3.

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

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

The description clearly states the verb 'Create' and the resource 'cycle', making the basic purpose evident. However, it does not differentiate from sibling tools like updateCycle or completeCycle, which are similar actions on the same 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?

The description provides no guidance on when to use this tool versus alternatives, prerequisites, or scenarios where it might be inappropriate. It is a single sentence with no usage context.

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

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

The annotations already indicate this is a non-read-only, non-idempotent, non-destructive operation. The description adds no additional behavioral context, such as side effects, permission requirements, or consequences of missing required fields (title). It simply restates that it creates a document, providing no value 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 a single, front-loaded sentence, which is highly concise. However, given the tool's complexity (13 parameters), it is under-specified; it lacks any structure or additional context that would help the agent use it effectively. It is terse but not 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?

With 13 parameters and only a one-line description, the definition is incomplete. It does not explain the return value (despite having an output schema), clarify when to use this vs. other create tools, or mention that documents can be associated with teams, projects, cycles, etc. An agent would need to inspect the schema heavily to understand the tool's capabilities, making it inadequate for a tool with this complexity.

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

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

Schema description coverage is 100%, so each parameter is individually documented. The tool description does not add any further semantic meaning, such as how parameters relate (e.g., teamId vs projectId) or any default behaviors. Since the schema carries the full weight, a baseline score of 3 is appropriate.

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

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

The description clearly states the action ('Create') and the resource ('Linear document'), which is sufficient to distinguish it from sibling tools like linear_updateDocument or linear_archiveDocument. It is specific and not a tautology, though it is minimal and does not elaborate on what a document entails or how it relates to other entities.

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?

There is no guidance on when to use this tool versus other create tools (e.g., createIssue, createProject) or when to avoid it. No prerequisites, ownership requirements, or alternative selection criteria are provided, leaving the agent to infer usage from the 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?

The description gives no behavioral transparency beyond the act of creation. It does not disclose side effects, required permissions, ownership implications, or what happens to connected projects. The annotations are all false and provide no safety hints, so the description carries the full burden of disclosure, and it fails to address any of it. There is no contradiction but also no meaningful information.

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 short—one sentence that essentially paraphrases the tool name. While it is concise, it is under-specified and adds no value beyond the title. There is no front-loading of critical constraints or guidance. This is a case of under-specification rather than effective conciseness, as it fails to earn its limited word count.

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 complex tool with 8 parameters, an output schema, and many related sibling tools (getInitiatives, updateInitiative, archiveInitiative, etc.), the description provides almost no context. It does not explain what an initiative is in Linear, how it relates to projects or roadmaps, what the output looks like, or any typical usage patterns. The agent would be left without sufficient guidance to call this tool correctly in most 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?

The input schema has 100% description coverage, with each parameter (name, icon, color, status, content, ownerId, targetDate, description) having a short explanatory description. Since the schema already documents the parameters, the description does not need to add details. However, the tool description doesn't provide any additional context about how parameters interact or which are essential beyond the required name field. 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 states 'Create a new initiative' which clearly indicates the verb and resource. It is unambiguous and directly conveys what the tool does. However, it does not differentiate from other 'create' tools like linear_createProject or linear_createRoadmap, though the resource name itself provides some distinction. The description is a restatement of the tool's name with no added nuance.

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?

There is no guidance on when to use this tool versus alternatives. It neither explains under what circumstances an initiative should be created nor contrasts with related operations like updateInitiative or archiveInitiative. The description provides no context about prerequisites, workflow, or distinctions from sibling tools.

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

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

Annotations indicate not read-only, not idempotent, not destructive. Description adds no behavioral context beyond 'create'—e.g., no mention of side effects, duplicate handling, or required permissions. Annotations provide minimal safety info, but description fails to elaborate.

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

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

Single sentence, front-loaded with action and resource. No wasted words; every part earns its place.

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

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

Output schema exists (context signal), so description does not need to explain return values. Tool has 4 parameters with schema coverage, so description is sufficient for creation context. Slight deduction for lack of usage guidance, but overall 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?

Schema description coverage is 100% with clear descriptions for all 4 parameters. Description does not add extra meaning beyond what schema already provides, so baseline 3 is appropriate.

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

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

Description clearly states 'Create a new initiative update' with a specific verb and resource. It distinguishes from siblings like linear_updateInitiativeUpdate (update) and linear_getInitiativeUpdates (read).

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

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

No guidance on when to use this tool versus alternatives. No prerequisites or exclusions mentioned. Sibling tools include update, archive, unarchive for initiative updates, but description does not help differentiate usage.

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

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

Annotations already communicate that this is not read-only, not idempotent, and not destructive, so the description adds no behavioral detail beyond what the name and annotations imply. It does not mention side effects, required preconditions, or duplicate-submission behavior, and there is no contradiction with 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 a single, front-loaded sentence with no filler or redundancy. It communicates the essential operation efficiently and leaves parameter details to the schema.

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

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

The input schema and output schema cover the data contract well, but the description is not fully complete for tool selection: it omits usage guidance around closely related tools and provides no practical context about creation behavior. For a create operation with 16 parameters and many sibling tools, this is adequate but has clear 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%, and all 16 parameters have meaningful descriptions, so the schema carries the semantic weight. The tool description itself adds no parameter-level information, which matches the baseline of 3.

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

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

The description clearly states the core action: create a new issue in Linear. It is obvious this tool creates an issue rather than updating, searching, or archiving one, but it does not explicitly differentiate itself from closely related siblings such as linear_createIssueFromTemplate.

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 about when to use this tool versus alternatives like linear_createIssueFromTemplate, linear_updateIssue, or linear_createIssueRelation. The only usage signal is the verb 'create,' which is implicit rather than explicit.

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

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

The annotations already signal that this is a mutating, non-idempotent operation, and the description adds the key behavioral fact that the issue is created by applying a template. However, it does not disclose side effects such as whether template defaults are copied, whether overrides replace them, or any result details, so it only partially exceeds what annotations already convey.

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

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

A single, front-loaded sentence with no filler. It states the operation and the template source immediately and spends no words on anything an agent can read from the schema or annotations.

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 an 8-parameter tool with a fully described schema and an output schema, the brief description plus structured fields is nearly complete for invocation. The main missing contextual element is guidance on when this should be used instead of the plain createIssue tool, but that gap is already captured in usage guidelines.

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

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

Schema description coverage is 100%, so the baseline applies. The description itself names no parameters, but the schema already documents all eight fields clearly, including which overrides are optional, so the description does not need to add parameter-level meaning.

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

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

The description uses a specific verb and resource ('Create a new issue') and the qualifier 'from a template' clearly separates it from the sibling linear_createIssue, which creates an issue from scratch. It tells an agent exactly what resource and operation this tool performs.

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 given about when to choose this tool over linear_createIssue or other sibling tools. The description does not state conditions, exclusions, or alternatives, leaving the agent to infer usage from the name and schema 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 the tool is not read-only, not destructive, and not idempotent. The description adds minimal behavioral context beyond stating it creates relations, but does not disclose side effects, permissions, or whether existing relations are overwritten.

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

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

The description is a single, concise sentence that immediately conveys the tool's purpose. It is front-loaded and contains no unnecessary words, earning its place efficiently.

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 parameter set, full schema coverage, and output schema presence, the description is mostly sufficient. It could mention whether relations can be created multiple times or if duplicates are handled, but overall it provides adequate context for a straightforward mutation.

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 each parameter already has a description. The description only paraphrases the 'type' enum values without adding new meaning. It does not clarify formats for issue IDs beyond what the schema provides, so it adds marginal 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 ('Create relations between issues') and lists example relation types ('blocks, is blocked by, etc.'), effectively distinguishing it from the sibling tool 'linear_deleteIssueRelation' which deletes relations.

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 does not provide explicit guidance on when to use this tool versus alternatives. It lacks context such as prerequisites, idempotency considerations, or comparison to similar tools like creating a relation from other objects.

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 all set to false (readOnly, openWorld, idempotent, destructive), so the description carries the full behavioral disclosure burden. It only states 'Create', which implies mutation, but provides no detail on idempotency, permissions, error handling for duplicate names, or any side effects. This falls short of what a create operation should disclose.

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

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

The description is a single, concise sentence with no fluff. It's front-loaded with the core action and object. This is appropriately minimal for conciseness, though it lacks detail that would earn a 5 on other dimensions.

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

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

The description is essentially a tautology of the tool's purpose. It provides no context on how to construct the templateData object (the nested JSON payload), which is a required parameter. It doesn't explain the output or differentiate from the many related create tools. The output schema exists but the description doesn't compensate for the under-specified templateData field, making the definition incomplete for an agent to use correctly.

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

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

Schema description coverage is 100%, so all parameters have descriptions (e.g., 'Template name', 'Template issue payload as JSON'). The tool description adds no additional parameter semantics. Baseline of 3 applies per rubric since the schema already documents parameters. The description doesn't clarify the structure of templateData beyond what the schema vague 'JSON' says.

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

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

The description states a specific verb and resource: 'Create a new issue template'. It clearly distinguishes from siblings like linear_createIssue (creates an issue) and linear_createIssueFromTemplate (creates an issue from a template). The purpose is unambiguous and immediately clear.

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 exclusions, prerequisites, or relationships to related tools like linear_updateIssueTemplate or linear_getIssueTemplates. The only implied context is the name, but no explicit usage guidance is given.

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

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

Discloses that it returns one-time client and optional webhook secrets, and that it cannot set certain scopes. Annotations (readOnlyHint=false, destructiveHint=false) are consistent. Does not mention all side effects, but sufficient for creation tool.

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 no wasted words. Front-loaded with purpose, then adds critical distinctions and limitations. Highly efficient.

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 complexity (11 params, output schema exists), description covers core purpose, key constraints, and result type. Could mention 'Managed' and 'alpha' more explicitly, but overall sufficient for an agent to make informed 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 coverage is low (18%), so description needs to compensate. It adds context for confirmSecretExposure by linking to secret return, but other parameters like imageUrl, grantTypes, webhookUrl are not explained. Description provides overall tool context but not detailed parameter guidance.

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

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

Clearly states verb (create), resource (alpha child OAuth application), and distinguishes from human setup flow. Differentiates from sibling OAuth tools by specifying it creates a managed application owned by the calling app.

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

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

Explicitly states it is not for human setup flow and cannot set distribution or pre-grant scopes, guiding agents to use it for automated initial creation. Could be more explicit about when to use vs other OAuth creation tools.

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

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

Annotations already indicate this is a non-read, non-destructive mutation. The description adds the basic fact that a new milestone is created, but does not disclose additional behavioral context such as permissions, side effects, idempotence nuances, or response behavior. With annotations in place, this is adequate but not enriched.

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

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

The description is a single, direct sentence with no filler or redundant detail. It front-loads the action and resource, which is appropriately concise for a straightforward create 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 simple create tool with full schema coverage, an output schema, and clear purpose, the description is largely complete. It does not spell out prerequisites like needing a valid projectId in prose, but the required parameter and schema already communicate that. The absence of further prose is not a critical gap.

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 five parameters (name, projectId, sortOrder, targetDate, description) are already documented in the input schema. The description adds no parameter-level meaning, but compensation is unnecessary given the full 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 a specific action ('Create') applied to a specific resource ('new project milestone in Linear'). It distinguishes this tool from the milestone-related siblings (getMilestones, updateMilestone, archiveMilestone) and from other create tools in the list, making the purpose unambiguous.

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

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

The description gives clear context: use this when creating a new milestone. It does not explicitly list alternatives or exclusions, but no other create-milestone sibling exists, and the get/update/archive siblings imply different lifecycle stages, so an agent can infer appropriate usage without further guidance.

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

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

The description discloses critical behavioral traits beyond the annotations: token is returned once, no refresh token, 30-day validity, and revocation of existing tokens on scope change. This is essential for safe agent usage, especially since annotations provide no behavioral hints.

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 three sentences long, front-loads the primary purpose and grant type, and each sentence adds essential information without redundancy. 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 the presence of an output schema for return values, the description covers the token creation lifecycle, usage target, validity, and side effects. It is complete for a token creation tool, including important warnings about token revocation.

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 80% (clientId lacks description). The description adds context about the impact of the scopes parameter (scope change revokes tokens), which enhances understanding beyond the schema's definition of enumerated values.

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 specifies the tool issues a scoped Linear app-actor access token via the client_credentials grant, explicitly stating it is for server-to-server pipelines. This distinguishes it from sibling tools that handle OAuth setup, authorization URLs, or application management.

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: it is for server-to-server pipelines, tokens have no refresh token, are valid for 30 days, and scope changes revoke existing tokens. However, it does not explicitly compare with alternative token generation methods 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.