Linear

Server Quality Checklist

Profile completionA complete profile improves this server's visibility in search results.

Latest release: v1.4.2
Disambiguation5/5
Each tool has a distinct action and target entity, with clear naming like linear_getProjectById vs linear_createProject. Even similar operations like archive vs delete are differentiated by entity. The descriptions further clarify the purpose, leaving no ambiguity between tools.
Naming Consistency5/5
All tools follow a strict 'linear_<verb><Entity>' pattern, with verbs like get, create, update, delete, archive, etc., and entities in camelCase. This consistency makes it predictable for an agent to infer the tool for any operation.
Tool Count3/5
With 198 tools, the set is very large. While it covers the extensive Linear API, it may overwhelm agents and exceed typical MCP server scopes. The count is borderline too high, though each tool serves a specific purpose.
Completeness4/5
The tool set covers CRUD-like operations for most Linear entities (issues, projects, roadmaps, releases, etc.) and includes admin and integration tools. Minor gaps exist, such as missing delete for projects and milestones (only archive), but the lifecycle is generally well-covered.
Average 3.4/5 across 160 of 198 tools scored. Lowest: 1.9/5.
See the Tool Scores section below for per-tool breakdowns.
- 1 of 1 community issues answered or closed in the last 6 months
- 19 commits in the last 12 weeks
- Last stable release on August 29, 2026
- No critical vulnerability alerts
- No high-severity vulnerability alerts
- No code scanning findings
- CI status not available
This repository is licensed under MIT License.
This repository includes a README.md file.
No tool usage detected in the last 30 days. Usage tracking helps demonstrate server value.
Tip: use the "Try in Browser" feature on the server page to seed initial usage.
This repository includes a glama.json configuration file.
If you are the author, simply .
If the server belongs to an organization, first add glama.json to the root of your repository:
```
{
  "$schema": "https://glama.ai/mcp/schemas/server.json",
  "maintainers": [
    "your-github-username"
  ]
}
```
Then . Browse examples.
Add related servers to improve discoverability.

How to sync the server with GitHub?

Servers are automatically synced at least once per day, but you can also sync manually at any time to instantly update the server profile.

To manually sync the server, click the "Sync Server" button in the MCP server admin interface.

How is the quality score calculated?

The overall quality score combines two components: Tool Definition Quality (70%) and Server Coherence (30%).

Tool Definition Quality measures how well each tool describes itself to AI agents. Every tool is scored 1–5 across six dimensions: Purpose Clarity (25%), Usage Guidelines (20%), Behavioral Transparency (20%), Parameter Semantics (15%), Conciseness & Structure (10%), and Contextual Completeness (10%). The server-level definition quality score is calculated as 60% mean TDQS + 40% minimum TDQS, so a single poorly described tool pulls the score down.

Server Coherence evaluates how well the tools work together as a set, scoring four dimensions equally: Disambiguation (can agents tell tools apart?), Naming Consistency, Tool Count Appropriateness, and Completeness (are there gaps in the tool surface?).

Tiers are derived from the overall score: A (≥3.5), B (≥3.0), C (≥2.0), D (≥1.0), F (<1.0). B and above is considered passing.

Tool Scores

Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint false, idempotentHint true, and destructiveHint false, but the description adds no behavioral context beyond that. It does not mention side effects, the scope of updates, or any operational details, so it adds no value over 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise but in this case it is under-specified rather than appropriately sized. It omits essential information, so it is not a model of conciseness; it is incomplete.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 10 parameters, an output schema, and multiple sibling tools, the description is completely inadequate. It does not explain the tool's behavior, parameter semantics, or usage constraints, leaving an agent with insufficient information to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 10%, and the tool description provides no parameter meanings. With 9 undocumented parameters and a single generic sentence, the description fails to compensate for the low schema coverage. The only described parameter (id) is covered by the schema, but the rest remain unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update team settings' states the action (update) and resource (team), so it is minimally clear about the tool's general purpose. However, it does not specify which team settings or differentiate from other update tools like linear_updateProject or linear_updateCycle, making it vague but not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is zero guidance on when to use this tool versus alternatives. No mention of prerequisites, contexts, or exclusions. The description provides no information to help an agent decide when to call this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness2/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose1/5
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.
Usage Guidelines2/5
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.
Behavior1/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are all false (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), so the description carries the full burden of behavioral disclosure. It does not mention whether the operation is idempotent, what happens on duplicate team names or keys, permission requirements, or any side effects. The description simply restates the action without adding behavior details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no waste. However, it is under-specified to the point of being unhelpful. It is appropriately short but lacks structure to convey required information, so it does not earn a higher score.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 9 parameters, an output schema, and no annotation hints, the description is grossly incomplete. It does not mention required fields (only name), optional settings, defaults, or expected outcomes. This level of detail is inadequate for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 11% (only 'name' is described in the schema). The tool description does not elaborate on any of the nine parameters, such as 'key', 'icon', 'visibility', etc. It fails to compensate for the lack of schema documentation, leaving agents without clues about parameter meanings or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new team' clearly identifies the verb (create) and the resource (team). It distinguishes from sibling tools like linear_updateTeam and linear_archiveTeam. However, it lacks any elaboration on scope or specifics, so it's clear but minimal.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, such as needing an organization context, or when it would be better to use team creation over updating existing teams. The description is purely declarative without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint=true and destructiveHint=false, but the description adds no behavioral context. It does not explain what 'all' entails (e.g., all for the current user, all across organizations), whether it is reversible, or what happens to already-read notifications. The description fails to add 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.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only one sentence, which is under-specified. While concise, it fails to earn its place by providing minimal useful information beyond the tool name. Important details like scope or parameter usage are missing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (one optional parameter, output schema exists), the description is extremely incomplete. It does not explain the return value, the effect on multiple pages of notifications, or any side effects. The description is insufficient for an AI agent to understand the tool fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one optional parameter 'limit' (integer), but the description does not mention it or explain its purpose (e.g., capping the number of notifications marked as read). With 0% schema description coverage, the description should clarify parameter semantics but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Mark all notifications as read' clearly states the action and resource, but does not distinguish from the sibling tool 'linear_markNotificationAsRead' which handles single notifications. The word 'all' provides some scope, but it remains vague about whose notifications or the organizational scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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_markNotificationAsRead' for individual notifications, or 'linear_getUnreadNotificationCount' for reading. No prerequisites, context, or use-case recommendations are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 additional behavioral details (e.g., side effects, permission requirements). The description 'Update' aligns with annotations but provides no extra transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but too brief for the tool's complexity. It fails to convey necessary details, sacrificing completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness1/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 6 parameters, no schema descriptions, and an output schema, the description is woefully incomplete. It does not explain return values, parameter semantics, or usage context, making it insufficient for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 6 parameters (id, url, label, secret, enabled, resourceTypes) with 0% description coverage. The tool description provides no explanation of these parameters, leaving the agent unable to determine their meaning or valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (update) and resource (ordinary workspace webhook). It distinguishes from other webhook tools like create or delete, but doesn't elaborate on what 'ordinary' means relative to other webhook types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., createWebhook, rotateWebhookSecret). Lacks context on prerequisites or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior1/5
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.
Conciseness2/5
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.
Completeness1/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond what the annotations already declare (readOnlyHint=true, idempotentHint=true, destructiveHint=false). It does not disclose pagination behavior, sorting options, what fields are returned, or any potential side effects. With annotations covering safety, the description fails to add value such as rate-limit implications or output structure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness2/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely terse (one short sentence), but this is under-specification rather than effective conciseness. It omits critical operational details, so the brevity is not earned—it sacrifices necessary information for the sake of brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with four parameters and an output schema, the description is inadequate. It does not mention the required issueId, what the limit controls, how orderBy works, or the meaning of includeArchived. Although the output schema exists, the description leaves too much to inference, making it incomplete for reliable agent use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning the description does not explain any of the four parameters (issueId, limit, orderBy, includeArchived). It does not compensate for the lack of schema descriptions; in fact, it ignores them entirely, leaving the agent to infer parameter meaning solely from names and types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('attachments for an issue'), which is specific and distinct from sibling tools like linear_addAttachment. It conveys the essential purpose without ambiguity, though it does not elaborate on what constitutes an 'attachment' in this context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 does not mention when this is the appropriate tool (e.g., for retrieving all attachments for an issue) or when to use other tools like linear_addAttachment or linear_getIssueById. No context or exclusionary conditions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint: false, destructiveHint: false, and idempotentHint: false. The description adds no behavioral context beyond the word 'create,' which merely aligns with the readOnly hint. It does not disclose the mutation's effects, authentication requirements, or what happens on creation. With annotations present the bar is lower, but the description still contributes almost nothing beyond them. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, efficient and front-loaded. It is appropriately sized - no filler - but this is under-specification rather than concise richness. It avoids waste but also avoids substance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
This is a mutation tool with 7 parameters (including resourceTypes, whose valid values are undocumented and have no enums) and an output schema. The description does not explain what event types are acceptable, whether the secret is required or auto-generated, or how team scoping works. Even though an output schema exists, the tool's behavior and parameter semantics are under-explained for a create operation of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate for parameter meaning. It does not - no mention of url, resourceTypes, secret, label, or teamId. However, the schema property names themselves (url, secret, enabled, teamId, allPublicTeams) are largely self-explanatory, and resourceTypes is reasonably inferable as 'the event types to subscribe to.' The description adds zero value here, but the schema names carry some semantic weight.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
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 webhook for integration events.' This distinguishes it from sibling operations like getWebhooks, updateWebhook, deleteWebhook, and rotateWebhookSecret, where the verb alone clarifies the intent. It is clear and unambiguous, though it does not explicitly contrast with the update/delete siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 the webhook siblings (getWebhooks, updateWebhook, deleteWebhook, rotateWebhookSecret). No context about prerequisites, when a webhook should be created, or when to prefer another sibling is given. The agent must infer usage entirely from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what the annotations already provide (readOnlyHint, idempotentHint, destructiveHint). It does not mention pagination, sorting behavior, or what data is returned. The annotations indicate a safe read operation, but the description misses the opportunity to add context about the response structure or constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (4 words) and front-loaded, but it is too minimal. While concise, it does not provide enough context to be maximally useful. It could include a brief note on what a membership includes or the effect of optional parameters without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and the presence of a complete output schema (not shown but noted), the description is functionally adequate but leaves room for improvement. It does not mention the scope of results (e.g., all memberships for a team) or how pagination works, but the schema covers the parameters. The description is bare minimum for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all four parameters (limit, teamId, orderBy, includeArchived), so the schema already fully documents each parameter. The description adds no additional meaning beyond the schema. Baseline 3 is appropriate 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.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get team memberships' states the action (get) and resource (team memberships) clearly, but it is a tautology that merely restates the tool name. It lacks any additional context to distinguish it from sibling tools like linear_getTeams or linear_updateTeamMembership, though the verb 'get' implies read-only and the resource is specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The sibling tools include related actions (add, remove, update, get teams), but the description does not mention when to choose this one, e.g., for listing all memberships vs. modifying them. The read-only annotation hints at appropriate use, but the description itself offers no explicit direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the agent knows it's a safe read. The description adds no additional behavioral context (e.g., pagination, rate limiting, whether archived webhooks are included by default). The schema suggests filtering ability but the description does not mention it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundancy. It is front-loaded, but the brevity sacrifices necessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 optional parameters and a list operation, the description is too minimal. It does not mention that there is an output schema (which covers return values) or how to filter results, leaving gaps in usability for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should explain parameters like `limit`, `teamId`, `orderBy`, and `includeArchived`. It fails to do so, offering no guidance on their meaning or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a list of webhooks, which fits its name and distinguishes it from siblings like `linear_getWebhookById` (single webhook) or `linear_createWebhook`. However, it does not specify the scope (e.g., all webhooks, per team) or mention that filtering is possible via parameters.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_getWebhookById` or when not to use it. The description lacks context on prerequisites, expected use cases, or boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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 extra disclosure about side effects, such as idempotency, or the need for a valid notification ID.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise and front-loaded. However, it may be too brief, sacrificing clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with a single parameter and output schema, the description is incomplete. It fails to specify what 'id' represents and lacks any usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the lone parameter 'id'. The agent must infer it refers to a notification ID, which is insufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb+resource: 'Mark a notification as read' describes the core action. However, it does not distinguish from the sibling 'linear_markAllNotificationsAsRead', which also marks notifications as read but for all.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 'linear_markAllNotificationsAsRead'. The description omits any context about single vs bulk operation or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness4/5
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.
Completeness1/5
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.
Parameters1/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness2/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description confirms deletion but adds no additional behavioral context, such as side effects or requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise and front-loaded. However, it is too terse and could include more useful information without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive operation with one parameter, the description is minimal. While an output schema exists, the description lacks important context about parameter format, error handling, and idempotency implications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'id' with 0% schema description coverage. The description does not elaborate on what 'id' refers to, leaving the agent without necessary context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a webhook' is a clear verb+resource statement. It distinguishes itself from sibling tools like linear_createWebhook and linear_getWebhooks.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as when to archive or deactivate. Prerequisites and error conditions are not mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no behavioral context beyond the search action itself, but it does not contradict the annotations. Since an output schema exists, return-format details are unnecessary here, keeping this at a baseline 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler, which is efficient. However, for a 6-parameter search tool with ambiguous sibling relationships, the description is under-specified rather than genuinely concise — it omits useful content rather than trimming excess.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 6 parameters and an intentionally generic sibling set, this description is insufficient. It does not explain how search behaves (e.g., fuzzy vs. exact, text matching scope), how it differs from linear_getIssues, or any limits/edge cases. The annotations and output schema cover some ground, but the text itself leaves an agent without clear guidance.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% across all 6 parameters, so the schema already documents each field (query, states, teamId, projectId, assigneeId, limit). The description adds no parameter-level meaning beyond what the schema provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose3/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search') and resource ('issues'), which is clear at a surface level. However, it does not differentiate from the sibling linear_getIssues, which likely returns the same resource with similar filtering. The phrase 'various filters' is vague and could describe several issue-listing tools in the sibling set.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like linear_getIssues, linear_searchReleases, or linear_getIssueById. No context, exclusions, or alternative routing is provided, leaving the agent to guess which search/list tool fits its task.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness3/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false (modifying) and destructiveHint=false (not destructive), but the description adds no additional behavioral context, such as permissions required 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at 5 words, but lacks necessary elaboration. Could be more informative without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters and an output schema, the description is insufficient. It does not explain the tool's full capabilities, default behavior, or how the response is structured, despite the output schema existing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description does not add any meaning beyond what is already in the schema (e.g., what each parameter does is already documented in the schema).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it creates a new project in Linear, which is a specific verb and resource. However, it does not differentiate from siblings like linear_updateProject or linear_archiveProject, but among the many tools, it is clear enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool vs. alternatives such as linear_updateProject or related project management tools. 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With all annotations set to false, the description carries full responsibility for behavioral disclosure. It does not mention any side effects, permissions required, or what happens upon creation. It adds no behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (single sentence), but it sacrifices informativeness. It is not overly long, but it lacks structure and fails to convey important details expected for a creation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of creating a release pipeline (6 parameters, output schema present), the description is far too minimal. It does not explain the return value, any constraints, or the relationship to other pipeline tools. This is incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 6 parameters, so the schema already documents them. The description adds no additional meaning or context for any parameter, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb ('Create') and the resource ('new release pipeline'), making the core action unambiguous. However, it lacks specificity to differentiate from sibling tools like 'createRelease' or 'createProject' that also use 'Create' as the verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., 'updateReleasePipeline' or 'archiveReleasePipeline'). There are no prerequisites, constraints, or use-case hints included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, indicating a write operation, and the description's 'Create' is consistent. However, the description adds no additional behavioral context such as potential side effects (e.g., uniqueness constraints on label names), required auth scopes, or idempotency implications. Given annotations cover the basic safety profile, the absence of any extra disclosure yields a score of 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (one sentence), which is concise, but it is under-specified rather than efficiently informative. It does not front-load critical information about required parameters or usage; it simply restates the obvious. It earns its place minimally by clarifying the resource 'label for a team', but could be more useful with a bit more context.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with 5 parameters (2 required) and an output schema, the description is inadequate. It does not explain the purpose of the label in the context of a team, mention that teamId is required, or clarify the optionality of parentId and description. While the schema covers parameter definitions, the description fails to provide any operational context that would help an agent decide when and how to invoke this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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, color, teamId, parentId, description) have their own descriptions. The tool description adds no extra meaning beyond that, so the baseline of 3 is maintained. No additional parameter semantics are provided in the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Create a new label for a team' states a specific verb (create) and resource (label for a team), which is clear and distinguishes it from sibling getter tools like linear_getTeamLabels. It is not a tautology since it adds the 'for a team' qualifier that the name implies but doesn't state. Slightly more detail about the label's scope could push it to 5, but this is sufficient.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 that a team must exist, any constraints on label names, or that this is the correct tool for creating a label as opposed to linear_createIssueLabel (which is used for adding labels to issues). No context is given for when a create operation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, idempotentHint=true, and readOnlyHint=false. The description adds no additional behavioral context beyond what annotations already provide, such as cascading effects or authentication needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, which is concise but overly minimal. It could include brief usage context or parameter clarification without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's destructiveness and existence of sibling operations like archiveProjectUpdate, the description lacks sufficient context for an agent to differentiate and apply safely. Output schema exists, but behavior and decision cues are missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% (single 'id' parameter with description). The description does not add any meaning beyond the schema, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a Linear project update', using a specific verb and resource. It distinguishes from siblings like archiveProjectUpdate by implying irreversible deletion, but the differentiation is not explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 archiveProjectUpdate or updateProjectUpdate. The description does not mention prerequisites, consequences, or context for choosing delete over other operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. However, the description adds no behavioral context such as default ordering, pagination behavior, or what constitutes 'active' versus archived. It does not explain the effect of the includeArchived parameter.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (7 words, one sentence). It is efficient but omits important parameter details that could be briefly noted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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, return format details are covered elsewhere. However, with 3 undocumented optional parameters and no explanation of defaults or behavior (e.g., does includeArchived override 'active'?), the description is incomplete for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 3 parameters (limit, orderBy, includeArchived) with 0% description coverage. The description does not explain any parameter semantics, leaving agents to guess their purpose and valid values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'list of active integrations', making the tool's purpose immediately obvious. No sibling tools overlap with this specific function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor does it indicate prerequisites or context. Agents receive no help in choosing this tool over others like linear_getIntegrationsById (if it existed).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no additional behavioral traits such as pagination behavior, result limits, or that it returns a list. With annotations present, the description should add context but fails to do so meaningfully.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, making it concise. However, it sacrifices completeness for brevity, omitting important filter options like stageId and includeArchived. Every sentence should earn its place, but this one is too vague.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of 5 optional parameters and an output schema, the description is insufficiently detailed. It mentions only three filter types but ignores stageId and includeArchived, leaving the agent unaware of full capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with each parameter already described. The tool description partially repeats schema information (e.g., 'by term, version, or pipeline name') but does not add new meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search' and the resource 'releases', and specifies the search criteria (by term, version, or pipeline name). However, it does not explicitly distinguish this tool from siblings like linear_getReleases or linear_getReleaseById, missing a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 when to search vs. when to fetch a single release or list all releases, leaving the agent 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false, destructiveHint=false, idempotentHint=true. The description adds no behavioral context such as required permissions or effect on existing data.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, but arguably too minimal. It could include more detail without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 12 parameters and an output schema (not shown), the description provides no information about return values, required state, or side effects, leaving the agent underinformed for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description does not add any extra meaning to parameters beyond their schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a customer' clearly states the verb and resource, and distinguishes it from siblings like create or delete. However, it could be more specific about which fields are updatable, but the schema provides that detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 createCustomer or deleteCustomer. No prerequisites or context about when updates are appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description only says 'Update', which implies mutation. Annotations already indicate it is not read-only and not destructive. The description adds no additional behavioral context (e.g., side effects, permissions, rate limits).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely short (two words), which is concise but at the cost of completeness. It is not front-loaded with useful information; it is minimal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (9 optional parameters, output schema exists), the description is too brief. It does not explain what the update returns, any side effects, or how to use related fields effectively. The output schema is present but not leveraged in the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 9 parameters are described in the schema (100% coverage). The tool description does not add further meaning beyond the schema, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states 'Update a customer need', indicating the action and resource. It is straightforward, though it does not differentiate from sibling update tools like 'linear_updateCustomer'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus alternatives, such as 'linear_createCustomerNeed' or 'linear_archiveCustomerNeed'. No exclusions or context given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description simply restates the mutation intent ('create') without adding behavioral detail. It does not disclose constraints like uniqueness of names, allowed type values, color format, position handling, or what happens on duplicate creation, and the annotations provide only basic write hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words and is immediately clear about the core action. It is concise but extremely minimal, roughly restating the tool name rather than adding meaningful elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a create operation with required fields like 'type' and 'color' that have no enums or format hints, the description leaves the agent without enough context to correctly populate these parameters. Even though an output schema exists, no guidance is provided on domain-specific constraints or how this tool fits into the broader workflow management flow.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all six parameters and their basic meanings. The description adds no additional parameter semantics, such as what 'type' values are valid or how 'position' affects ordering.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('create') and resource ('workflow state'), which clearly distinguishes it from sibling tools like linear_updateWorkflowState and linear_getWorkflowStates. However, it provides no additional context about workflow states beyond the name and requires domain knowledge to understand what a workflow state actually is.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as linear_updateWorkflowState or linear_getWorkflowStates. There is no mention of prerequisites, when not to use it, or how it relates to team workflow configuration.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and readOnlyHint=false, so the description's 'Delete' verb adds no new behavioral context. It does not disclose side effects, irreversibility, or required permissions, which would increase transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the purpose, making it concise and front-loaded. It could include minor additional context without losing conciseness, but it is efficient and to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (1 parameter, output schema exists, destructive hint in annotations), the description is minimally complete. However, it lacks any usage context or behavioral nuance, making it adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a single parameter 'id' described as 'The ID of the release note to delete'. The tool description adds no additional meaning beyond the schema, 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a release note' clearly states the action and resource. It distinguishes from sibling tools like create, update, and get. However, it lacks additional specificity such as 'permanently delete' or 'cannot be undone', which could further clarify the operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 vs alternatives like updateReleaseNote or archiveReleaseNote. It does not specify prerequisites or consequences, leaving the agent to infer usage from context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already indicate the operation is non-read-only, non-idempotent, and non-destructive, and the description does not contradict them. But the description adds no behavioral context beyond the word 'Duplicate' — it does not say whether a new issue is created immediately, what gets copied, or what side effects occur. For a mutating tool, this is a clear gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one short sentence with no redundant material, and the core action is front-loaded. It is concise, though the brevity borders on under-specification rather than optimized clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter tool with full schema coverage and an output schema, the description provides a minimum viable understanding, and return values are not needed because an output schema exists. However, it omits side-effect or result semantics — such as that a new issue is created and which properties are copied — so the agent must infer behavior from the tool name.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and the issueId parameter is already documented as 'ID or identifier of the issue to duplicate (e.g., ABC-123)'. The description adds no parameter-level detail, but with full schema coverage the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Duplicate') and resource ('an issue'), clearly identifying the operation. It avoids the tautology problem of merely restating the tool name. However, it does not differentiate this tool from sibling issue-related tools like createIssue, updateIssue, or archiveIssue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use duplicateIssue versus createIssue, updateIssue, transferIssue, or archiveIssue. It also does not state prerequisites or scenarios where duplication is the appropriate choice. This is essentially no usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, covering the safety profile. The description adds no behavioral context beyond that: it does not mention pagination, ordering, or the return format. Since the safety is already known, the description should add value by explaining how the tool behaves (e.g., returns a list, requires exactly one parent ID), but it does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence that states the action and scope without wasted words. It is appropriately concise for its purpose, with no filler or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 optional parameters spanning multiple resource types, the description is too minimal. It does not clarify that at least one parent identifier is required, whether multiple can be combined, or what the default ordering/pagination behavior is. Although the output schema exists and covers return values, the agent is left without guidance on how to select the correct parameter, making the description incomplete for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter is already documented with its meaning. The tool description adds a small amount of context by listing the parent resource types, which implies that one of the corresponding ID parameters should be provided. However, it does not specify that exactly one is required or how to choose among them, so it does not significantly elevate understanding beyond the schema. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (get comments) and the resource (comments) and lists the parent entities (issue, project, initiative, update, document content). It distinguishes from mutating comment tools (create/update/delete) but does not explicitly differentiate from any other getter like getIssueHistory, which could also return comments. Slightly broad but not a tautology, and 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.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit guidance on when to use this tool versus alternatives. It does not mention that this is the read-only counterpart to createComment/updateComment/deleteComment, nor does it state any conditions or exclusions. The only implied usage is that it is for retrieving comments, but the tool does not clarify whether to prefer this over other retrieval methods like getIssueHistory.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows it's a safe read operation. The description adds no further behavioral context (e.g., default limit, pagination, rate limits). With annotations covering safety, 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (5 words). While concise, it lacks important context like scope (e.g., all customer needs or filtered) and return structure. It could be more informative without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 does not mention return format, pagination, or default ordering. With 7 optional filter parameters, the description should provide more guidance on how they combine and what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters with descriptions, so the baseline is 3. The tool description adds no additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves customer needs from Linear. The verb 'Get' and resource 'customer needs' are specific. However, it doesn't differentiate from similar retrieval tools like getCustomerNeedById, but the name itself provides distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 getCustomerNeedById, createCustomerNeed, or other search tools. No exclusions or context about filtering vs. listing all needs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive, ensuring the agent understands it's safe. The description adds no further behavioral context, such as rate limits, pagination, or what happens if no statuses exist. With annotations covering the safety profile, a score of 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.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just five words, but it may be too terse to provide adequate clarity. While brevity is good, it sacrifices informative structure; a slightly longer description could improve understanding without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool has three optional parameters, an output schema, and clear annotations, the description fails to explain the broader context of what customer statuses are or how they relate to other customer entities. The agent lacks information about the purpose of statuses and typical usage patterns, leaving the description incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all three parameters, so the schema itself documents their meaning. The description does not add any additional insight or context beyond what the schema already provides, meeting the baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'get' and the resource 'customer statuses', and indicates the source 'from Linear'. However, it does not distinguish this tool from similar siblings like 'linear_getCustomerTiers' or provide a precise definition of what customer statuses are.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 compared to alternatives such as 'linear_getCustomers' or 'linear_getCustomerById'. There is no mention of use cases, prerequisites, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral information beyond what annotations already provide. Annotations indicate the tool is read-only and idempotent, but the description does not add context about what statistics are included or any constraints. It is not contradictory, but it does not enrich behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it is so brief that it sacrifices useful context, so it does not earn a top score but is still appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description is minimal. However, given the large number of cycle-related sibling tools, the lack of context on what distinguishes this from related tools makes it incomplete for correct selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds no additional information about the 'id' parameter. Since the schema fully documents the parameter, the description does not need to repeat it, but it also does not add any clarification about expected format or usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves statistics for a cycle, using a specific verb and resource. However, it does not differentiate from sibling tools like linear_getCycleById or linear_getActiveCycle, which also relate to cycles, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. With many cycle-related siblings such as getCycleById, getActiveCycle, and getCycleIssues, an agent could easily be confused. The description offers no context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the agent knows this is a safe read. However, the description adds no behavioral context—no mention of defaults (e.g., default limit, whether archived templates are excluded by default), pagination, or response structure. It essentially restates the tool's name without disclosing any additional behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no unnecessary words. It is front-loaded with the core action and resource, making it easy to scan. However, it is so minimal that it verges on under-specification, though for a simple list operation this is acceptable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity and the presence of an output schema, the description is mostly adequate. However, it fails to clarify the scope of 'issue templates'—whether it returns all templates across the organization or only those for a specific team. The existence of getTeamTemplates suggests a scoping distinction that is not addressed, leaving an agent potentially calling the wrong list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (limit, orderBy, includeArchived) has a clear description. The tool description itself adds no parameter-level detail, but with full schema coverage, the baseline of 3 applies. The description does not clarify any relationships or constraints beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('a list of issue templates'), which distinguishes it from individual-issue-template operations like getIssueTemplateById. However, it does not explicitly differentiate from similar list tools like getTeamTemplates or getProjectTemplates, leaving the exact scope (all templates vs. team-specific) ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. With multiple sibling tools for fetching templates (e.g., getTeamTemplates, getIssueTemplateById), an agent has no criteria to select between them. There is no mention of context, preferred scenarios, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is known. The description adds no behavioral context beyond the trivial 'Get a list' - it does not mention default ordering, archived handling, or result shape. Given the annotations, the bar is lower, but the description still contributes nothing to behavioral understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words, and the purpose is stated upfront. It is appropriately concise, though it could incorporate usage guidance without becoming verbose. No structural issues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While an output schema exists (so return format is covered), the description omits any usage context such as when to filter by archived, how ordering works, or how this complements the other roadmap tools. An agent calling this tool would have to infer all behavioral nuances from the schema, making the description incomplete for a list operation that supports optional filters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; all three parameters (limit, orderBy, includeArchived) have descriptions. The tool description does not add any parameter-specific meaning beyond what the schema already provides. Baseline of 3 is appropriate since the schema carries the full semantic load.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('list of roadmaps'), which is specific and distinguishable from the sibling linear_getRoadmapById that targets a single roadmap. However, it does not explicitly contrast itself with other list getters like linear_getProjects, so it lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to choose this tool over alternatives. It does not mention scenarios where a caller should prefer linear_getRoadmapById for a single roadmap, nor does it clarify default behavior around archived items or pagination. Agents must 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds nothing beyond the annotations; it does not disclose any additional behavioral traits like pagination or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness3/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 7 words, which is concise but lacks essential details. It is front-loaded with purpose but sacrifices completeness for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema, the tool has 4 parameters and a close sibling. The description does not explain what audit events are, whether pagination is supported, or any other context, leaving the tool under-specified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description does not add any meaning to the parameters. It fails to explain what 'includeArchived' or 'orderBy' entail, leaving the agent to infer from parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'audit events', specifying the scope 'for a specific user', which distinguishes it from the sibling tool `linear_getOrganizationAuditEvents`.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_getOrganizationAuditEvents`. There is no mention of context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds no extra context about side effects (e.g., notification behavior) or how to unsubscribe. Minimal disclosure 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It is appropriately short for a simple tool, though no structural elements are used.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no nested objects, output schema present), the description is adequate but lacks context on what subscribing entails in practice (e.g., notification behavior). It meets minimum completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (issueId). The description adds an example format (e.g., ABC-123), which helps but is not significant. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Subscribe to issue updates' clearly states the verb (subscribe) and resource (issue updates). It distinguishes itself from sibling tools like createIssue or updateIssue. However, it does not specify what type of updates (e.g., notifications) are involved.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 getIssueById or setIssuePriority. There is no mention of prerequisites or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already claim idempotentHint=true, readOnlyHint=false, and destructiveHint=false, so the safety profile is covered. However, the description adds zero behavioral context beyond the bare mutation statement — nothing about what fields get replaced, whether empty bodies clear content, or what the response contains. For a mutation tool the description should carry more weight.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single efficient sentence with no wasted words. It is minimal but not padded; the brevity is genuine conciseness rather than under-specification, though it could carry more useful content in the same space.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 7 parameters, an output schema, and a non-trivial mutation behavior, yet the description delivers only a bare purpose statement. The output schema covers return values, but the description omits usage context, side effects, and what triggers the various optional fields. A richer description is warranted for a tool this parameterized.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 7 parameters individually documented (body, quotedText, subscriberIds, resolvingUserId, etc.), so the schema does the heavy lifting. The description adds no parameter-level detail, which matches the baseline-3 expectation for full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update'), a clear resource ('comment'), and the 'existing' qualifier that distinguishes it from create/delete siblings. It doesn't explicitly name siblings, but the purpose is unambiguous and the name itself disambiguates from linear_createComment and linear_deleteComment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 exclusions, and no prerequisites stated. With siblings like linear_updateIssue and linear_createComment nearby, an agent gets no help deciding when updating a comment is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, which aligns with 'update'. The description adds no behavioral context beyond what annotations provide, such as side effects, authorization needs, or error handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. It is efficient but could be slightly more informative without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 12 parameters and no explicit explanation of side effects or return value (though output schema exists), the description is too brief. It lacks completeness for complex usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the input schema provides detailed parameter descriptions. The description does not add any additional meaning beyond 'update an existing project', which is baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('update') and the resource ('an existing project in Linear'). However, it does not distinguish this tool from siblings like linear_archiveProject or linear_createProject, which are also project-related actions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_archiveProject, linear_createProject). There is 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, idempotentHint=true, and destructiveHint=false. The description adds no extra behavioral context, such as what gets modified, idempotency implications, or any side effects. It contributes nothing beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the core purpose. It contains no filler and is appropriately sized for a simple update operation, though it lacks any structural elaboration beyond the one-line statement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large set of sibling tools, the description provides minimal context. It does not explain when this tool is intended (e.g., modifying roadmap properties like name or color) or how it relates to other roadmap operations (create, archive, get). The presence of an output schema covers return values, but the decision to call this tool relies on the name and schema, not the description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with descriptions for all six parameters (id, name, color, ownerId, sortOrder, description). Since the schema fully documents parameters, the description adds no additional semantic meaning. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing roadmap' clearly states the action (update) and resource (roadmap), and the word 'existing' distinguishes it from create and archive siblings. It is specific enough to identify the tool's purpose, though it does not enumerate the updatable fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It does not mention that it is only for modifying existing roadmaps (not creating), nor does it point to any related tools like linear_createRoadmap or linear_archiveRoadmap. The choice relies entirely on the tool name and schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the key behavioral context that notifications are scoped to the current user, which is beyond the name alone. However, it doesn't mention any pagination behavior, sorting details, or rate limits, so it adds some value but not rich context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that front-loads the core purpose. It is appropriately short and avoids verbosity. However, given that it could include a brief note on parameter usage without bloat, it misses an opportunity for structure; but as is, it is concise and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists (which covers the return shape), the description fails to explain the parameters (limit, orderBy, includeArchived) which are likely essential for filtering and sorting results. The tool has three optional parameters with no guidance, so completeness is low for an agent wanting to call it effectively. The description is too sparse to fully contextualize the tool's capabilities.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% — neither the description nor the schema provides any explanations for the parameters (limit, orderBy, includeArchived). The description says nothing about what these parameters do, how they interact, or their default values. With zero parameter context and a terse description, an agent is left guessing at semantics, making this a critical gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), a resource ('notifications'), and a scope ('for the current user'). This clearly distinguishes it from sibling tools like markNotificationAsRead, getUnreadNotificationCount, and markAllNotificationsAsRead, and an agent can immediately understand what it does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 (e.g., getUnreadNotificationCount for just counts, or markNotificationAsRead for mutating). The usage is only implied by the tool's purpose, with no explicit exclusions or conditions. For example, there is no mention of whether this returns only unread notifications or all notifications, which could mislead an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and readOnlyHint=false. The description adds no additional behavioral context 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (three words), but it achieves clarity in its brevity. However, it could include more useful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having an output schema and annotations, the description lacks important context such as permanence of deletion, side effects, or differences from archiving. It is insufficient for a destructive tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'id', which is well-documented in the schema. The description adds no further meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and the resource (customer need). However, it does not differentiate from the sibling tool 'linear_archiveCustomerNeed', which has a similar action but different outcome.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_archiveCustomerNeed'. No prerequisites or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds no additional behavioral context (e.g., pagination, sorting defaults, rate limits). Since annotations cover safety, the description is adequate but not enhanced. No contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (one sentence). It is front-loaded and wastes no words. However, it could be structured better to include key information like that it returns a list of customers. Still, it is appropriately sized for a simple retrieval operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having a full parameter schema and output schema, the description is minimal. It doesn't explain that this is a list endpoint, that multiple filters can be combined, or that default sorting or limit apply. For a tool with 8 optional parameters and many sibling tools, the description leaves out important context for proper usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all 8 parameters, each with clear descriptions. The tool description does not add any extra meaning or usage hints beyond the schema. Thus it meets the baseline expectation but provides no added value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get customers from Linear' clearly states the action and resource. However, it doesn't distinguish from sibling tools like 'getCustomerById' or 'getCustomerNeeds', which also retrieve customer data but with different scope. The purpose is clear but lacks differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 'getCustomerById' for a single customer or search endpoints. The description does not mention filtering capabilities or usage context (e.g., listing all customers). An agent would have to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint: true, idempotentHint: true, destructiveHint: false) fully cover the safety profile, so the description only needs to add context beyond that. The description's 'Get' is consistent with readOnly behavior, and it adds no contradictory information. However, it adds no additional behavioral context (e.g., pagination, return format, that it returns a list) beyond what the schema already indicates. With annotations present, the bar is lower, so a score of 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no redundancy. It's concise and front-loaded, stating the action and resource immediately. However, it's almost too brief—given the tool's complexity (10 parameters, many filters), a slightly more detailed description would be more useful without becoming verbose. It earns a 4 for efficiency, losing a point for under-specification.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the presence of an output schema (which documents return values), the description is incomplete for a tool with this many optional filters and numerous sibling getters. It doesn't explain that this is the general-purpose listing tool that can be filtered by project, team, cycle, issue, etc., nor does it clarify when to use this over more specific document getters. The description is too minimal to be fully contextual for an agent to correctly choose this tool among the many document-related siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All ten parameters have descriptions in the schema (100% coverage), so the schema fully documents each parameter. The description adds no new parameter meaning; it doesn't clarify how filters interact or provide examples. Since the schema does the heavy lifting, the baseline of 3 applies. The description doesn't compensate for any gaps, but none exist at the field level.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get workspace documents from Linear' clearly identifies the action (get) and resource (documents), and the plural 'documents' implies a list operation, which distinguishes it from getDocumentById. However, it doesn't specify that this is a general listing tool with filters, and it's somewhat vague about the scope ('workspace documents' could be interpreted as all documents or a specific category). It's reasonably clear but not fully distinguishing among the many document-related siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like linear_getProjectDocuments, linear_getTeamDocuments, or linear_searchDocuments. It doesn't mention that this is the general-purpose document listing tool with optional filters, nor does it explain when to prefer specific getters. The schema shows filters like projectId, teamId, etc., but the description gives no advice on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds no additional behavioral details (e.g., pagination, rate limits). Adequate given annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, very concise. Could add brief parameter guidance without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists, so return values are covered. But description lacks parameter semantics and usage guidelines, which are needed for full completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 3 parameters with 0% description coverage. Tool description does not explain any parameter meaning. No value added beyond parameter names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Get' and resource 'audit events for the organization'. Distinguish from sibling linear_getUserAuditEvents which is per user.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 linear_getUserAuditEvents. No context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no behavioral details (e.g., pagination behavior or subscription scope). Given annotation coverage, a 3 is appropriate—the description does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It is front-loaded with the core purpose, making it easy to scan. No redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 optional parameters and an output schema. The description lacks details on subscription types, filtering meaning, and response structure. While the output schema may fill some gaps, the description does not provide enough context for an agent to decide whether this tool is appropriate for a given subtask, especially given the large sibling set.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, meaning the schema provides no parameter descriptions. The tool description does not elaborate on the parameters' meaning (limit, orderBy, includeArchived) beyond what the schema types and enums convey. This forces the agent to infer usage, which is inadequate for such coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('subscriptions') scoped to the current user. It is specific enough to distinguish from sibling tools, as no other tool retrieves subscriptions. However, it does not clarify what type of subscriptions (e.g., issue, project) are returned, which could be ambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, or any context about prerequisites or expected results. The description solely states the function with no comparative or contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true and idempotentHint=true, so the description's 'Revoke' aligns with these. However, the description does not add additional behavioral context such as immediate invalidation of the session or effects on the user. With annotations present, a score of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits crucial details like how to obtain a sessionId or that it is required. Given the output schema exists, the description could still benefit from minimal usage context. The completeness is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the 'sessionId' parameter (e.g., its source or format). This fails to add meaning beyond the raw schema, which is insufficient for an AI agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Revoke a specific session' clearly states the action (revoke) and the resource (session), distinguishing it from sibling tools like linear_logoutAllSessions and linear_logoutOtherSessions by specifying 'specific'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 its siblings. It does not mention prerequisites, alternatives, or context for choosing this over linear_logoutAllSessions or linear_logoutOtherSessions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent, non-destructive, non-read-only. Description adds no extra behavioral context beyond what annotations provide, such as permissions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single clear sentence with no wasted words. Front-loaded and appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Output schema exists but description does not indicate return values or success/failure behavior. For a simple mutation, adequate but could be more complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has high coverage (100%) with description for initiativeId. Description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description states 'Unarchive an initiative' with specific verb and resource. It distinguishes from siblings by resource name, but does not explicitly differentiate from other unarchive tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 unarchiveProject or unarchiveMilestone. No prerequisites or conditions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive. The description adds no extra behavioral detail (e.g., permissions, impact on related items).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence that conveys the essential action. No wasted words or extraneous details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with annotations and output schema, the description covers the core action but lacks context about usage order (e.g., only applies to archived releases) or relation to sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the schema already describes releaseId as 'The ID of the release to unarchive'. The description adds no further meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb (Unarchive) and resource (release), making the action unambiguous. However, it does not differentiate from sibling linear_archiveRelease beyond the opposite verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., archiveRelease, completeRelease). No context about prerequisites or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true, destructiveHint=false, and readOnlyHint=false, so the safety profile is covered. But the description adds nothing beyond the one-line purpose—no note about partial updates, what happens to unspecified fields, required permissions, or rate limits. With annotations present, some credit is given, but the description is semantically empty 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with zero waste. Every word earns its place, and the purpose is front-loaded without redundancy or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema and fully documented parameters, so the structured data carries much of the burden. The description is adequate for a moderate-complexity update tool but is thin—it doesn't clarify whether it patches only provided fields or replaces the whole initiative, which an agent would benefit from knowing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 9 parameters are documented in the schema itself. The description adds no parameter-level meaning beyond what the schema provides, matching the baseline of 3 for high-coverage schemas.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Update') and resource ('an existing initiative'). The purpose is clear and actionable, and among siblings like linear_createInitiative, linear_archiveInitiative, and linear_deleteInitiative, the verb distinguishes it. However, it doesn't explicitly name siblings to differentiate from, which keeps it from a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 the sibling alternatives (create, archive, delete, unarchive) or on when an update is appropriate. There is no mention of prerequisites or contexts that should route an agent here.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and readOnlyHint=false, so the description adds no new behavioral context. It does not mention that it performs a partial update (only provided fields are changed), which is important given the 18 optional parameters. The description essentially restates the tool's name without revealing side effects, error conditions, or that fields are overwritten selectively.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with zero redundancy. It is appropriately minimal for a tool with a well-documented schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 18 parameters, 100% schema coverage, an output schema, and annotations covering idempotency, the description is not required to enumerate every field. However, it omits key nuances like partial-update semantics and any prerequisites (e.g., the issue must exist). For a complex mutation, more guidance would be helpful, but it does not reach the level of being incomplete enough to mislead.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each of the 18 parameters including a description. The tool description adds nothing about parameters beyond what the schema already provides. Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Update') and resource ('issue'), with the specific domain (Linear). It is distinct from most siblings, though a few specialized update tools (e.g., setIssuePriority, assignIssue) could overlap. Lacks explicit differentiation but the generic nature is understandable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this versus the many specialized issue tools (e.g., assignIssue, setIssuePriority, addIssueLabel, updateIssueCustomField). No exclusions or conditions are mentioned, leaving the agent to infer when the generic update is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate mutation (readOnlyHint=false) and no idempotency, but the description adds no behavioral context beyond stating the action. It does not disclose side effects, permissions, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the purpose with no unnecessary words. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
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 omits context such as required permissions, pipeline existence, and constraints like position uniqueness. For a tool with 7 parameters, it is insufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with detailed descriptions for all 7 parameters. The description adds no additional meaning, so 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new release stage in a pipeline' with a specific verb and resource, and distinguishes it from sibling tools like linear_getReleaseStages, linear_updateReleaseStage, and linear_archiveReleaseStage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 context on prerequisites, such as needing an existing pipeline, or exclusions for 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already set readOnlyHint=false, destructiveHint=false, and idempotentHint=false, but the description adds no further behavioral context. It does not disclose what happens on creation, any side effects, permission requirements, or whether name collisions are handled. Since annotations cover the basic safety profile, the description contributes nothing extra, making this a minimal score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler. It front-loads the verb and resource, making it immediately clear. For its brevity, it is perfectly concise and structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 11 parameters, including nested objects and an output schema, yet the description is only a one-liner. It does not explain what a saved view is, how to structure filters, or which parameters are essential beyond the required 'name'. Annotations provide no additional context. This is 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.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all 11 parameters have descriptions. The tool description itself adds no parameter information, but the schema already documents each field. While some schema descriptions are vague (e.g., 'Raw filters object'), the coverage is complete, so the baseline of 3 applies. The description does not enhance the schema's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a Linear saved view' with a specific verb and resource, and the API reference 'createCustomView' adds specificity. It differentiates from siblings like linear_updateSavedView, linear_deleteSavedView, and linear_getSavedViews by the action 'create'. The purpose is unambiguous and distinguishes this tool from its close relatives.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description does not mention prerequisites, scenarios, or conditions that would make this the correct choice. It simply states the action without context, leaving the agent to infer usage solely from the name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds 'move to trash,' implying soft deletion, but does not clarify whether the trash is recoverable or for how long. Missing details like required permissions, side effects on related entities (e.g., projects, milestones), or error behavior. The added value beyond annotations is minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: a single sentence with no unnecessary words. Every word contributes to meaning, and the essential information (action and target) is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that this is a destructive tool with an output schema available, the description lacks critical context such as reversibility, impact on linked objects, permission requirements, and error handling. The output schema may cover return values, but the behavioral and operational completeness is insufficient for an agent to use the tool safely.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema fully documents the single parameter 'initiativeId.' The description does not add any additional meaning or constraints beyond the schema's own description. Baseline 3 applies, and no extra value is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete an initiative (move to trash)' clearly states the verb (delete) and resource (initiative), with a parenthetical clarification that it moves to trash rather than permanently removing. This distinguishes it from siblings like archiveInitiative and unarchiveInitiative, which have different lifecycle effects.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 like archiveInitiative or updateInitiative. The description does not mention prerequisites, recovery options, or situations where deletion should be avoided. An agent would have to infer usage from the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds no extra behavioral context (e.g., consequences, permissions). It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. It is front-loaded and efficient, but could slightly expand on usage without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description doesn't need to explain return values. However, for a deletion tool, lacking any guidance on recovery or effects makes it barely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the parameter description in the schema is adequate. The tool description adds no further meaning beyond what's in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (delete) and resource (release pipeline). However, it does not differentiate from similar tools like 'archiveReleasePipeline' which also removes a pipeline but may retain it. The distinction is unclear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 archiving. No context about prerequisites or when deletion is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not add any behavioral context beyond the annotations. Annotations already declare it as read-only, idempotent, and non-destructive, but the description fails to mention that it returns a list or any pagination behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence, which is concise. However, it is too terse to provide full value; it 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.
Completeness3/5
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 thorough annotations, the description is adequate. However, it lacks explanation of what customer tiers are or typical usage, leaving some gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The tool description adds no additional meaning beyond the schema, so it meets the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets customer tiers from Linear, using a specific verb and resource. It distinguishes from sibling tools like linear_getCustomers and linear_getCustomerById.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as linear_getCustomers or linear_getCustomerNeeds. The description assumes the agent knows the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is clear. The description adds no additional behavioral context (e.g., pagination, default limit, team scope). With annotations covering key traits, a score of 3 reflects minimal added value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The single-sentence description is concise and front-loaded. However, it is slightly too terse, missing important scope information (e.g., that teamId filters the list). Still, it contains no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has an output schema and only two optional parameters, the description is adequate but incomplete. It does not clarify the behavior when teamId is omitted (e.g., whether it returns cycles from all teams). The existence of many sibling cycle tools raises the need for clearer distinction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%: both parameters ('limit' and 'teamId') are fully described in the schema. The description adds no extra meaning beyond the schema, so 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a list of all cycles' clearly indicates a list operation on cycles. However, it does not differentiate from sibling tools like 'linear_getCycleById' or 'linear_getActiveCycle', and it omits that the list can be filtered by team via the teamId parameter.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_getCycleById' (single cycle) or 'linear_getActiveCycle' (active cycle). The agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, making the non-destructive behavior clear. The description simply restates this with 'Get details', adding no new behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence with no unnecessary words. It is efficient, though it could be slightly more informative without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and an output schema exists to describe the return value, the description is adequate for a simple query. It does not explain potential errors or authorization, but these are not critical for a read-only operation with clear annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the schema describes the 'id' parameter as 'The ID or slug of the release to retrieve'). The description adds no additional meaning, so a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and the resource ('details of a specific release'), distinguishing it from siblings like getReleases (list) and searchReleases (search). However, it is somewhat generic and could specify what kind of details are returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as getReleases for listing all releases or getReleasePipelineById for pipeline details. An agent must infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, clearly conveying safety. The description adds no additional behavioral context beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence. It is concise and front-loaded, but could be more explicit about the tool's role (listing vs. searching).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations are rich, the description is adequate but minimal. It does not clarify pagination, filtering behavior, or how it differs from similar tools, which would be helpful for a list operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides complete descriptions for all three parameters (100% coverage), so the description does not need to add parameter info. It meets the baseline but does not enhance understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'release pipelines', making the tool's purpose understandable. However, it lacks differentiation from siblings like linear_searchReleases, which also retrieves releases but with search capabilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as linear_getReleasePipelineById or linear_searchReleases. The description does not mention context, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotentHint: true and destructiveHint: false, but the description does not expand on behavioral aspects such as what happens to the issue after removal (e.g., it remains in the backlog) or required permissions. It adds no context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that is front-loaded and contains no unnecessary words. It is concise but could include a bit more context without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (2 parameters, removal operation) and the presence of an output schema and clear annotations, the description is minimally adequate. However, it lacks details about the effect on the issue or any preconditions, which would help an agent invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions ('The ID or identifier of the issue to remove' and 'The ID of the release to remove the issue from'). The tool description does not add further meaning, but the schema already provides sufficient information, so baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove an issue from a release' clearly states the action (Remove) and the resource (issue from a release). The tool name also reflects this, and among siblings there are similar tools for adding issues to releases and removing issues from projects, which are distinct.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_addIssueToRelease' or when it is appropriate. There is no mention of prerequisites (e.g., the issue must be in the release) or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare idempotentHint=true and destructiveHint=false, which align with the restore action. The description does not add behavioral context beyond these annotations, such as permission requirements or state changes, but does not contradict them either.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, four-word sentence that is concise and front-loaded. For a simple operation, this is appropriate, though it could include brief context without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 existence of an output schema, the description is minimally adequate. However, it omits any mention of the effect of unarchiving (e.g., reappearance in lists) or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The lone parameter 'id' is described in the schema as 'ID of the initiative update to restore', which is clear. With 100% schema coverage, the description adds no extra meaning beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Restore an archived initiative update' clearly states the action (restore) and the resource (initiative update), distinguishing it from sibling tools like 'archiveInitiativeUpdate' and other unarchive operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines1/5
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, when not to use, or references to sibling tools like 'linear_archiveInitiativeUpdate'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that this is a write, idempotent, non-destructive operation. The description adds the partial-update requirement — that an id alone is insufficient and at least one mutable field must be supplied. It does not explain side effects or validation behavior, but the annotation coverage reduces the burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is one direct front-loaded sentence with no filler. Every word contributes to the core action and the key usage requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with 5 parameters and only 20% schema coverage, the description is too thin. It omits field semantics, constraints, how to discover the workflow state id, and behavior when fields are omitted. The presence of an output schema reduces the need to explain return values, but the invocation guidance remains incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 20%, with only 'id' documented. The description says to provide id plus another field but does not explain the meaning, format, or constraints of 'name', 'color', 'position', or 'description'. It fails to compensate for the low schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action and resource: 'Update a workflow state.' This is unambiguous and distinct from a create/get operation. However, it does not explicitly differentiate itself from siblings like linear_createWorkflowState or linear_getWorkflowStates, relying mostly on the tool name and verb.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a useful operational rule: 'Provide id plus at least one other field to change.' This tells the agent what is required to invoke the tool. However, it does not explicitly say when to use this tool versus alternatives, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose4/5
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.
Usage Guidelines2/5
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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and no destructive action. The description adds no additional behavioral context (e.g., error handling, permissions, data format). With annotations present, the description contributes minimally.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise (3 words) and front-loaded. It wastes no words, but could include additional context without harming conciseness (e.g., specifying return type). Still effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with output schema and annotations, the description is adequate. It covers the core functionality, though it could mention that it returns a single customer object (but output schema covers that).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter 'id' described as 'Customer ID'. The description adds no extra meaning beyond the schema; baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a customer by ID' clearly specifies the action (get) and resource (customer), with the key identifier (ID). It distinguishes from sibling tools like linear_getCustomers (list all) and linear_getCustomerNeeds (get needs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 indicate when to use this tool versus alternatives like search or listing, nor does it mention prerequisites or context for invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, indicating a safe read operation. The description adds no additional behavioral context such as authorization needs, rate limits, or return format details, missing an opportunity to add 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no redundant words. Every part of the description serves a purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with one parameter and an existing output schema, the description is minimally sufficient. However, it could provide context about what an initiative update is or how to obtain the ID, which would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter (id) described as 'ID of the initiative update to retrieve'. The description does not enhance parameter meaning further, but baseline 3 is appropriate since schema already sufficiently documents it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the tool retrieves a specific initiative update by ID. This distinguishes it from sibling tools like linear_getInitiativeUpdates (list) and linear_createInitiativeUpdate (create), 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.
Usage Guidelines2/5
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 vs alternatives. The usage is implied by the name and parameters, but there's no mention of requiring the update ID or when not to use it (e.g., if you need to list all updates). Siblings like linear_getInitiativeUpdates are listed but not referenced.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already accurately declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds 'recent' which hints at ordering/filtering behavior, but it does not elaborate on how recency is defined (e.g., by updatedAt or createdAt) or whether the list is flat and unpaginated. This is minimal added context beyond annotations, so a baseline 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, direct sentence containing the essence of the operation with no filler. The verb is front-loaded and the sentence is immediately actionable, making it as concise and well-structured as possible for a list tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the tool is simple (one optional parameter) and an output schema exists (per context signals), the description need not explain return values. However, the vagueness of 'recent' and the lack of any statement about scope (team, project, global) leave an agent uncertain whether this returns all accessible issues or a filtered subset. Since output schema covers the shape, completeness is acceptable but not strong.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the sole parameter 'limit' with its type, default, and purpose, giving 100% coverage. The description adds nothing about parameters, so it relies entirely on the schema. With high schema coverage, a score of 3 matches the baseline for this dimension.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb ('Get') and resource ('a list of recent issues'), which is distinct from tools that fetch a single issue (linear_getIssueById) or search (linear_searchIssues). However, the qualifier 'recent' is vague and does not precisely define the scope (e.g., all issues across the workspace or a specific team), leaving some ambiguity about the exact set returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool over alternatives such as linear_getProjectIssues, linear_getCycleIssues, or linear_searchIssues. The description implies a general recent-issue listing but does not mention exclusions, prerequisites, or the presence of more targeted list tools, forcing the agent to infer usage based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description does not need to restate safety. It adds minimal behavioral context beyond the basic read operation, but does not contradict annotations. The description contributes little extra, but there is no requirement to duplicate annotation information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that is appropriately concise and front-loaded. There is no wasted wording, and it gets straight to the point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with an output schema and annotations covering safety, the description is functional. However, given the large family of document-retrieval siblings, it lacks context on how project documents differ from team, issue, or initiative documents, which would help an agent select the right tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 no parameter-specific context beyond what the schema already documents (limit, title, orderBy, projectId, includeArchived). It does not compensate for or enrich the parameter meanings.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (get) and resource (documents) scoped to a particular Linear project. It is clear and unambiguous, but does not differentiate from many sibling document-retrieval tools (e.g., linear_getTeamDocuments, linear_getIssueDocuments), though the tool name itself conveys the project scoping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 the numerous sibling document tools. There is no mention of alternatives, exclusions, or the specific context that selects this tool over linear_getTeamDocuments or linear_getIssueDocuments.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as read-only, idempotent, and non-destructive. The description adds no behavioral details beyond the verb 'Get'. No contradiction 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with no filler words. Every word adds value without being verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (3 optional parameters, no required), the description is minimally complete. However, it could better clarify the scope relative to sibling tools and what constitutes a release note.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters have descriptions in the input schema, achieving 100% schema description coverage. The tool's description does not add any additional meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves release notes from Linear, using a specific verb and resource. However, it does not differentiate itself from the sibling tool linear_getReleaseNoteById, which retrieves a single note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_getReleaseNoteById or linear_getReleases. The description lacks context on typical use cases or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no behavioral detail beyond the name—no mention of pagination, ordering, or archived inclusion, but these are already in the schema. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with zero wasted words. It precisely conveys the tool's core action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the schema covers all parameters and an output schema exists, the description doesn't need to explain return types. However, it is minimal and offers no extra context (e.g., typical use cases, relationship to team labels or issue templates). It meets the minimum for a simple read operation but doesn't enhance understanding beyond the structured fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each parameter has explicit meaning in the schema. The description provides no additional parameter context, which is acceptable given the schema already documents all four parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Get' and the resource 'templates' scoped to a specific team, making the action and target obvious. It is distinguishable from sibling tools like linear_getIssueTemplates or linear_getProjects, though it doesn't explicitly differentiate itself in wording.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, no exclusions, and no context about prerequisites or typical scenarios. The single sentence implies usage but leaves the agent to infer when this read operation is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, so the description adds no extra behavioral context. It does not explain that all sessions including the current one are revoked, nor does it warn about potential data loss or authentication consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two words, containing no unnecessary information. It is front-loaded and direct, achieving maximum brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the destructive nature and lack of parameters, the description is insufficient. It does not clarify what 'all sessions' includes (e.g., current user session, API tokens) or the consequences. For a sensitive action, more detail is needed, even with an output schema present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist in the input schema, so the description cannot add parameter details. Schema coverage is 100%, and the baseline for zero-parameter tools is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Revoke all sessions' clearly states the action and resource, distinguishing it from sibling tools like linear_logoutSession (single session) and linear_logoutOtherSessions (other sessions). However, it lacks additional context about scope and effect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_logoutSession or linear_logoutOtherSessions. The description does not mention prerequisites, required permissions, or typical scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
While annotations already provide idempotentHint and destructiveHint, the description adds no behavioral context beyond the action name. It does not disclose side effects, permissions, or what happens to the issue after removal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is appropriately front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 an output schema, the description is adequate but leaves room for more context, such as prerequisites or the issue's new state.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds no additional meaning beyond what the schema provides, 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Remove an existing issue from a project' with a specific verb and resource. It distinguishes from the sibling tool 'linear_addIssueToProject' which performs the opposite operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 that the issue must already be in the project, nor does it reference the add counterpart for contrast.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat safety. It adds minimal behavioral context beyond that—no mention of default limit, sorting, or what gets searched (title/content is in the schema). The description is consistent with annotations, so no contradiction, but it provides little extra value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no redundancy. It states the core purpose directly and is well-structured for quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the output schema exists and the input schema covers all parameters, the description itself is very terse. It doesn't add context about the scope of documents, result behavior, or filtering options (though these are in the schema). For a simple search tool, it's adequate but minimal; more context like 'searches title and content' could help, though that's already in the parameter description.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already documented in the schema. The description adds no extra meaning; it simply echoes the 'term' parameter. According to the baseline, with high coverage, a score of 3 is appropriate because the description doesn't enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (search) and the resource (Linear documents), with a qualifier ('by term'). However, it does not explicitly differentiate from sibling search tools like linear_searchIssues or linear_searchReleases; the distinction is only implied by the tool name. A bit more specificity about what constitutes a document would improve it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. The description does not mention that it is specifically for documents (vs. issues or releases), nor does it suggest when to prefer linear_getDocuments or other search tools. The agent is left 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.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate readOnlyHint=false (mutation), destructiveHint=false, and idempotentHint=true. The description adds no behavioral detail beyond the bare action, such as whether the transfer affects issue history, other fields, or requires the target team to exist. It does not contradict annotations, but with the burden shifted to the description, it fails to disclose any side effects or prerequisites.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero fluff. It is front-loaded with the core action and avoids unnecessary detail. This is exemplary conciseness for a straightforward tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity of transferring an issue and the existence of an output schema, the description is minimally sufficient but lacks contextual details about side effects or preconditions. An agent can call the tool, but might be unaware of implications like changes to the issue's project or cycle. The description does not explicitly mention any constraints or consequences, leaving some gaps for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides clear, complete descriptions for both parameters (teamId and issueId) with 100% coverage. The description does not add any additional parameter semantics—it only restates the action. Baseline 3 is appropriate because the schema already carries the parameter information and the description does not enhance it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Transfer an issue to another team' clearly states the action (transfer) and the resource (issue) plus the destination (another team). It is specific and easily distinguishable from siblings like linear_updateIssue or linear_assignIssue, which deal with different modifications. The verb and noun combination makes 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.
Usage Guidelines2/5
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 conditions (e.g., requiring specific permissions, whether the issue must be open, or differences from assignIssue or updateIssue). An agent must infer usage solely from the name and general context, offering insufficient decision support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide idempotentHint=true and destructiveHint=false, so the description's minimalism is acceptable. However, it adds no extra behavioral context like auth requirements or side effects beyond 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no unnecessary words. Efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters and an output schema, the description is sparse but minimally sufficient. Output schema covers return values, so no further explanation needed. Could mention that the update returns the updated object.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
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 no additional meaning beyond the schema, which already has clear parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing initiative update' clearly states the action and resource, but does not differentiate from sibling tools like 'archiveInitiativeUpdate' or 'updateInitiative'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 creating or archiving an initiative update. Absent context for when this action is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description does not need to restate safety. It adds a validation expectation about providing another field, but does not describe error behavior or partial-update semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that states the action and the key calling constraint without any extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is low-complexity, has an output schema, and annotations cover the safety profile. The main gap is the missing explanation of owner/sortOrder semantics and lack of routing against add/remove alternatives, making it barely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Only the id parameter has a schema description (33% coverage). The description does not explain what 'owner' or 'sortOrder' mean or how 'role' maps to these fields, so it fails to compensate for the undocumented parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Update a user's role in a team.' This distinguishes it from sibling add/remove membership tools, though 'role' is slightly vague because the actual mutable fields are owner and sortOrder.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an operational constraint: 'Provide id plus at least one other field to change,' which tells the agent not to call with only an id. However, it does not mention when to prefer this over linear_addUserToTeam or linear_removeUserFromTeam.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness4/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness2/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior2/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations exist and are not contradicted. The description adds no behavioral context beyond creation, such as side effects or required permissions. With annotations present, score is adequate but uninspired.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence efficiently conveys the core purpose. No wasted words, but could be restructured to front-load key info. Minor room for improvement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Minimally complete given output schema and full parameter coverage. However, lacks usage context and behavioral details that would make it more helpful.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%. The description does not add meaning beyond what the schema already provides, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create', the resource 'project update', and the context 'for a Linear project'. It distinguishes from siblings like update, get, archive, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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., update or get). No mention of prerequisites or scenarios where this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true and idempotentHint=true. The description merely states 'Delete a customer', which is consistent but adds no additional behavioral context (e.g., whether deletion cascades to related entities, or if it's a soft/hard delete). 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, which fits a simple destructive action. It could be slightly more informative (e.g., one sentence), but it is not verbose and front-loads the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the operation is simple, the description is adequate. However, it does not clarify typical success/failure responses or side effects, which would be helpful for completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'id' with a description 'Customer ID', and schema coverage is 100%. The tool description does not add any extra meaning or constraints beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description is 'Delete a customer', clearly stating the specific verb (delete) and resource (customer). It distinguishes from sibling tools like linear_updateCustomer or linear_archiveCustomer, making it unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as linear_archiveCustomer (softer deletion) or linear_deleteCustomerNeed. There is no mention of prerequisites, irreversible consequences, or conditions for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context—it implies a scoped read operation but doesn't mention details like whether archived documents appear by default (handled via parameter) or output format. It is consistent with annotations, so no contradiction; the description adds some value but not rich 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero wasted words. It is concise, clearly states the primary purpose, and is front-loaded with the action and resource. There is no redundant elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only operation with a well-documented schema and clear annotations, the description is adequate. It doesn't explain return values, but an output schema exists to cover that. Some nuance about default behavior (e.g., limit default 25, archived excluded by default) is present in parameter descriptions, not needed here. The description is complete enough for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so each of the 5 parameters (cycleId, limit, title, orderBy, includeArchived) already has an individual description. The tool description adds no parameter-level detail beyond what the schema provides, which matches the baseline expectation for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('documents associated with a specific Linear cycle'), which clearly indicates the operation. It distinguishes from sibling document getters (e.g., linear_getProjectDocuments) by explicitly scoping to a cycle via the cycleId parameter. While it doesn't explicitly enumerate exclusions, the scope is unambiguous enough to avoid confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 alternative document retrieval tools (e.g., getProjectDocuments, getTeamDocuments). The description does not mention prerequisites, alternative selection conditions, or any caveats. The user must infer usage from the tool name and parameter alone, which is insufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering safety and idempotency. The description adds no extra behavioral context beyond the read-only action—no mention of return behavior, error handling, or authentication. It is consistent with annotations, so a baseline 3 is appropriate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant words. It is front-loaded with the verb and resource, making it immediately clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple get-by-id operation with an output schema present, the description is adequate. It does not need to explain return values because the output schema handles that. It implies the full document details, which is sufficient for an agent to call it correctly; however, it could marginally clarify that it returns the current state rather than history, but that is not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single 'id' parameter, and the description provides no additional semantics beyond what the schema already states. Baseline is 3; the description adds no nuance about the parameter's format or expected values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('details of a specific Linear document'), making it distinct from list/search operations. However, it does not explicitly differentiate from siblings like linear_getDocumentContentHistory, though the 'ById' suffix and parameter clarify the specificity. It is specific and not a tautology.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_searchDocuments or linear_getDocumentContentHistory. It does not mention conditions, exclusions, or context for selection, leaving the agent to infer 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the tool is safe. The description adds no further behavioral context beyond stating it 'gets updates'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words, but it could be slightly improved (e.g., specifying 'all updates' or a hint about pagination), so not a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 (not shown) and the simple nature of the tool, the bare minimum is provided. However, missing guidance on usage and behavioral details makes it adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described. The description does not add additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get updates for an initiative' uses a specific verb 'Get' and clearly identifies the resource as 'updates for an initiative', distinguishing it from siblings like getInitiativeUpdateById (single update) and CRUD tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No usage guidance is provided. The description does not state when to use this tool versus alternatives like getInitiativeUpdateById, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds no behavioral details beyond the purpose, such as what kind of changes are included (e.g., field changes vs. comments) or ordering of results, so it doesn't go beyond what annotations already provide.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no waste. It precisely communicates the action and nothing more.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with output schema and complete parameter descriptions, the description is adequate. It could mention the nature of the 'changes' (e.g., whether it includes comments or only field updates), but the output schema likely covers the return structure, so nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters fully documented. The description adds no additional parameter meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb 'Get' and resource 'history of changes made to an issue', making the tool's purpose unambiguous and easily distinguishable from siblings like linear_getComments or linear_getDocumentContentHistory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 that this is for tracking changes over time or contrast it with getting comments or document history, leaving the agent to infer usage entirely from the name and purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the fact that it returns a list, but does not elaborate on scoping (e.g., all labels vs team labels), whether archived labels are included, or sorting. It provides minimal behavioral context beyond the name, so a score of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It immediately states the action and resource, which is appropriately front-loaded and easy to scan. No extraneous information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with no parameters and an existing output schema, the description is mostly sufficient. However, it lacks clarification on scope (global vs team-specific), which is ambiguous given the sibling 'linear_getTeamLabels'. An agent might not know whether this returns all labels or a subset, so the description is slightly incomplete but not severely lacking.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema description coverage is 100% trivially. Per rubric, a baseline of 4 applies for no parameters, and the description correctly does not need to explain any parameter semantics. It adds no unnecessary detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource: 'Get a list of issue labels'. It is specific enough to know it retrieves label data, but it does not differentiate from the sibling tool 'linear_getTeamLabels', which likely has a different scope (team-specific vs global). The purpose is clear but not distinguished.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 the existence of 'linear_getTeamLabels' or any conditions for choosing between them. There is no exclusion or context about scope, so an agent has no information to decide which label-listing tool fits the request.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. Description adds no new behavioral context beyond restating schema parameters (pipeline/stage filters). Missing pagination or rate limit info.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single concise sentence with no fluff. Could benefit from structure (e.g., listing filters) but efficient for its purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple list tool with output schema. Missing pagination or default limit context beyond schema parameter. Not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 5 parameters with descriptions (100% coverage). Description only highlights pipeline and stage filters, adding no new meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb 'Get' and resource 'releases' with explicit mention of optional filters. Distinguishes from siblings like getReleaseById and searchReleases.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for listing releases with filters, but no explicit when-to-use or alternatives. Could mention searchReleases for more flexible search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds the team-scoping behavior, but it does not disclose things like default limits, archived handling beyond the schema parameter, or pagination behavior; the schema partially covers these.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundant content. Every word earns its place, and the core meaning is immediately available to the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the rich output schema, fully described parameters, and safety annotations, the description supplies the essential context for a team-scoped read operation. It is adequate for invoking the tool correctly; the main missing element is explicit routing guidance among sibling document tools, already penalized in usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all five parameters, including teamId, limit, title, orderBy, and includeArchived. The description adds no additional parameter semantics beyond what the schema already documents, so 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.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get'), resource ('documents'), and scope ('associated with a specific Linear team'), making the tool's core function unambiguous. It is distinguishable from generic document tools like linear_getDocuments by the team-specific focus, though it does not explicitly name sibling tools to draw the contrast.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as linear_getDocuments, linear_searchDocuments, or linear_getProjectDocuments. Given the large sibling list with many document-related tools, the absence of any when-to-use or when-not-to-use direction leaves selection to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that it returns 'home resource sections and pinned documents or external links', which gives context about the response content. It doesn't mention pagination or error behavior, but for a simple read operation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no filler. It front-loads the verb and resource, making it immediately clear what the tool does. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the existence of an output schema and annotations covering safety, this is a complete description for a simple getter. It clearly states what is returned (home resource sections and pinned items). Nothing an agent needs to call it correctly is missing; it could optionally mention whether the response is paginated, but that's likely in the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% – the single parameter 'teamId' is documented as 'ID of the team whose home resources should be returned'. The description adds no further meaning beyond what the schema already conveys, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and clearly names the resource: 'team home resource sections and pinned documents or external links'. This distinguishes it from siblings like linear_getTeamLabels or linear_getTeamDocuments, though it doesn't explicitly name alternatives. The scope is clear enough for an agent to understand what this tool returns.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, nor any exclusion criteria. It simply states what it does. With many sibling getters (e.g., linear_getTeamLabels, linear_getTeamDocuments), the lack of explicit routing makes it harder for an agent to select this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations thoroughly declare readOnlyHint, idempotentHint, and non-destructive behavior, so the description doesn't need to repeat those. The description adds no behavioral details beyond the schema (e.g., no mention of response size or pagination), but there is no contradiction. With strong annotation coverage, the bar is lower, and this meets the minimum.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with zero waste. It is front-loaded with the core action and resource, and includes the target scope ('for a team'). The structure is optimal for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a straightforward purpose with only two parameters and an existing output schema, so return values are handled elsewhere. Given the annotations covering safety and idempotency, the description is sufficient for an agent to call this correctly. It misses minor context like 'archived states are excluded by default', but that is inferable from the schema, so not a significant gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (teamId and includeArchived) are fully documented in the schema. The description adds no extra meaning or context for parameters, which is acceptable given the baseline of 3. The description's simplicity aligns with the schema's completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('workflow states for a team'). It distinguishes itself from siblings like linear_createWorkflowState and linear_updateWorkflowState by being a retrieval operation. However, it doesn't explicitly differentiate from other getters (e.g., linear_getTeamLabels) beyond the resource type, but the resource name is specific enough.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. There is no mention of conditions, prerequisites, or exclusions. For a simple getter, some implicit usage context exists (e.g., when need workflow states), but the lack of any explicit direction warrants a low score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. Annotations indicate destructiveHint=false and idempotentHint=true, but the description merely restates the action without explaining side effects (e.g., what happens if the project isn't in the initiative).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no unnecessary words. Efficiently communicates the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter removal operation with an output schema, this description is adequate. However, it lacks detail on prerequisites or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions. The tool description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Remove' and the resources 'project from an initiative', distinguishing it from the sibling 'linear_addProjectToInitiative'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., archiving a project). The context of removing from an initiative is implied but not elaborated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate destructiveHint=true, but the description adds no context about side effects like immediate invalidation of the old secret or impact on webhook callers. It is adequate but does not enrich 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of 7 words, front-loading the verb and resource with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is short but covers the core action. However, it leaves ambiguity about the required parameters and the output. Given the tool's simplicity and the presence of an output schema, the description is functional but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explain the parameters 'id' (presumably the webhook ID) or 'confirmSecretExposure' (a confirmation flag). The brief description provides minimal semantic support.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action 'Rotate' and the resource 'ordinary workspace webhook signing secret', distinguishing it from sibling tools like linear_rotateManagedOAuthApplicationSecret and linear_rotateManagedOAuthApplicationWebhookSecret.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 or when not to use it. The description does not mention prerequisites or conditions such as requiring confirmation of secret exposure, which is only implied by the required parameter.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false, so the description carries a lower burden. It states 'unarchive' but doesn't elaborate on behavior (e.g., restoring availability, permission needs). Adds marginal 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. Every word contributes to purpose clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the large set of sibling tools and moderate complexity, the description is too minimal. It lacks context about what unarchiving entails, constraints, or output (though output schema exists).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the schema already describes pipelineId. The description does not add new meaning beyond what is in the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Unarchive a release pipeline' uses a specific verb (unarchive) and resource (release pipeline), clearly distinguishing it from sibling tools like archiveReleasePipeline and other unarchive tools (e.g., unarchiveRelease).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, lacks prerequisites (e.g., pipeline must be archived), and does not contrast with similar unarchive operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a write operation (readOnlyHint=false) and idempotency (idempotentHint=true). The description adds the explicit null-clearing behavior, which is also in the schema, so it provides marginal value beyond annotations. It doesn't mention permissions or failure modes, but the annotations cover the safety profile adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that front-loads the main action ('Set or clear a custom field value') and includes the key edge case (null to clear) immediately. Zero filler words; every part earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with fully documented parameters and an output schema, the description is sufficient. However, it does not reference sibling tools like linear_getCustomFields for field discovery or clarify that it only works on issue custom fields (implied by name). This is a minor gap but not critical.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already thoroughly described including the JSON-compatible value types and null clearing. The tool description adds nothing beyond the schema, meeting the baseline for full coverage without redundant detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Set or clear' and the resource 'custom field value on an issue', which distinguishes it from siblings like linear_updateIssue that handle standard fields. It is specific but could more explicitly contrast with that sibling. The action and target are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_updateIssue, nor does it point to discovery tools like linear_getCustomFields. The only usage hint is the null-to-clear behavior, which is more of a parameter detail than a usage guideline.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide destructiveHint=true and idempotentHint=true, which the description aligns with but does not expand upon. No additional behavioral details (e.g., permissions, cascading effects) are offered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise – a single phrase captures the entire operation. No wasted words. Front-loaded and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete tool with full schema coverage and annotations, the minimal description is viable but lacks any additional context like expected response or error conditions. Could be improved by noting idempotency or success behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%; the schema's own description for 'id' is 'ID of the comment to delete'. The tool description adds no new semantic information beyond this.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description is 'Delete a comment' – a clear verb+resource combination that precisely states the tool's function. It distinguishes from siblings like createComment, updateComment, and getComments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use, prerequisites (e.g., must have comment ID), or alternatives. For a destructive operation, this context would help the agent make responsible choices.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the workspace-level scope, which is useful, but does not add other behavioral details like return structure or pagination; the output schema covers some of that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no filler. It front-loads the action and resource clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a no-parameter read-only tool with an output schema, the description is mostly complete. It could be improved by explicitly contrasting with the similar sibling getIssueCustomFields, but the core usage context is sufficiently clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema description coverage is 100%, so there is nothing for the description to clarify about inputs. The 0-parameter baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('custom field definitions'), and clarifies they are workspace-level. However, it does not distinguish itself from the similar sibling linear_getIssueCustomFields, so it misses full sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 such as linear_getIssueCustomFields. There is no mention of exclusions or selection criteria, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false. The description adds no behavioral context beyond what is already available, such as response structure or null handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single parameter, output schema available, clear annotations), the description is minimally adequate. However, it could include information about the response structure or error conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and describes the id parameter as 'ID of the cycle to retrieve'. The description does not provide additional meaning or format details beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific cycle' clearly identifies the action (get details) and the resource (a specific cycle via ID). It distinguishes from sibling tools like linear_getCycles (list) and linear_getActiveCycle (active cycle only).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as linear_getCycleStats or linear_getActiveCycle. It neither states prerequisites nor suggests scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description adds no additional behavioral context. However, it does not contradict annotations, and the tool appears safe and idempotent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no extraneous information. Every word serves a purpose, and it is appropriately front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
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 annotation coverage, the description is adequate but minimal. It does not mention that the tool returns a list or any common use cases, but the schema and annotations fill in the gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all parameters, so the description need not add parameter details. The baseline score of 3 applies as the description does not enhance comprehension beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'release stages', which is specific and distinguishes it from sibling tools that deal with other entities like releases, pipelines, or stages individually.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_getReleasePipelineById or linear_getReleaseById. The description lacks context on typical use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered by structured data. The description adds no additional behavioral context, which is acceptable for a simple read operation but does not go 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with zero waste. It immediately states the action and scope, making it easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values are documented externally. The tool is simple and the description, combined with the schema and annotations, leaves no critical information missing for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes all four parameters (teamId, limit, orderBy, includeArchived) with 100% coverage, so the description adds no new parameter information. The baseline of 3 applies because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and resource ('labels') with a scope ('specific team'), making the purpose clear. It doesn't explicitly compare to siblings like linear_getLabels, so it misses the highest mark.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as linear_getLabels. The intended use case is implicit from the name and description but never stated explicitly, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare `idempotentHint: true`, `destructiveHint: false`, and `readOnlyHint: false`. The description adds no extra behavioral context beyond 'remove', so it neither contradicts nor enriches 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.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (6 words) and front-loaded with the action. No fluff, but could include a short note about idempotency or non-destructive nature.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with an output schema and high schema coverage, the description is adequate. However, it lacks usage context and does not explain that it only removes the association without deleting the issue or cycle.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear parameter descriptions. The tool description does not add additional semantic value to the parameters beyond what the schema provides. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Remove' and the resource 'issue from a cycle'. It is specific and directly distinguishes this tool from siblings like `addIssueToCycle`, `getCycleIssues`, and other remove tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. It doesn't mention prerequisites (e.g., issue must be in cycle), when not to use, or any context about the lifecycle of cycles.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate non-read-only (readOnlyHint=false) and no destructiveness (destructiveHint=false), but idempotentHint=true. The description simply says 'remove', which implies mutation. The description does not add behavioral context beyond what annotations and schema already provide, such as whether the operation is reversible or requires special permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no unnecessary words. It efficiently conveys the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While schema and annotations provide adequate detail, the description lacks context about usage scenarios and potential side effects. Given the presence of sibling tools with similar operations, the description could be more informative about when to choose this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with detailed descriptions for all three parameters. The description does not add any additional meaning or context beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Remove a user from a team' clearly states the verb and resource, and it distinguishes itself from siblings like 'addUserToTeam' and 'updateTeamMembership'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives, such as whether it's appropriate to remove a user with active issues or what happens to parent team memberships. The explicit 'alsoLeaveParentTeams' parameter is mentioned in the schema but not in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey readOnlyHint=false (mutation), destructiveHint=false, and idempotentHint=true. The description adds no new behavioral details beyond restating the action. It doesn't mention permissions, response shape, or side effects. Given annotations cover the core safety profile, the description adds minimal behavioral insight, earning a 2.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with zero waste. It states the action, the resource, and the required parameter constraint efficiently. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 6 parameters, 1 required, low schema coverage, and an output schema (not shown). The description does not elaborate on the meaning or behavior of the optional fields, nor does it reference the output. With complex nested objects and sparse schema descriptions, the context is incomplete. Annotations cover safety but not parameter semantics or expected outcomes. A 2 reflects the significant gaps for an agent to call this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17% (only 'id' is described). The description states 'Provide id plus at least one other field' but does not explain the meaning of name, teamId, sortOrder, description, or templateData. With low coverage, the description should compensate but fails to explain any parameter semantics beyond the requirement to include at least two fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'update' and resource 'issue template', and explicitly requires 'id plus at least one other field to change'. This distinguishes it from create/get/archive template tools and from updateIssue. It's specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage: it tells the agent to provide id and at least one other field, indicating the tool is for modifying existing templates. It doesn't explicitly mention alternatives like createIssueTemplate or archiveTemplate, but the clear purpose and the requirement of an existing id provide sufficient context. No exclusions, but the scenario is clear enough for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true, indicating the mutation behavior. The description adds the API name but does not elaborate on side effects, reversibility, or error conditions. It provides minimal additional context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that conveys the essential information without any unnecessary words or filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple delete operation with one parameter and an output schema, the description is mostly complete. The only gap is the lack of context about prerequisites or consequences, but given the tool's simplicity, this is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, describing the 'id' parameter as 'ID of the saved view to delete'. The description adds no further semantics or format details, so it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Delete' and the resource 'saved view', and also references the underlying API method 'deleteCustomView'. This distinguishes it from sibling tools like create and update, which have different verbs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, such as when to delete a saved view as opposed to archiving or updating it. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds minimal behavioral context beyond what annotations provide — it does not mention pagination, response shape, or any side effects. Since the bar is lower with annotations, a 3 is appropriate because the description adds little value beyond structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource, and includes a clarifying clause about the included view types. There is zero wasteful language, and it conveys the essential purpose immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with complete parameter schema, safety annotations, and an output schema, the description provides the core information needed (what it returns and the scope). It lacks explicit guidance on when to prefer it over getSavedViews, but the name and description make that distinction implied. Minor omission keeps it from a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — all three parameters (limit, orderBy, includeArchived) are described in the schema. The description adds no extra meaning about parameters; it simply states the resource. With high schema coverage, the baseline is 3, and the description does not enhance parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Get favorite Linear views', and explicitly disambiguates that it includes both saved and predefined views. This clearly distinguishes it from sibling tools like linear_getSavedViews (which is specifically about saved views) and add/remove favorite tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, e.g., 'Use this instead of getSavedViews when you need both saved and predefined views' or any exclusions. An agent must 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds no extra behavioral context beyond confirming it is a read operation ('Get'), and it doesn't mention any rate limits, authentication, or response characteristics. Since annotations are rich, the description's minimal addition is acceptable, though it could note that the tool retrieves a single entity rather than a list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no wasted words. It front-loads the action and object, and the 'by ID' qualifier immediately clarifies the lookup nature. It is optimal for a get-by-id tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with only two parameters (one required), an output schema, and rich annotations, the description suffices. It correctly identifies the operation and resource. The only minor omission is not explicitly mentioning the includeProjects option, but since it is fully documented in the schema, the description is not incomplete. The tool's complexity is low, so it doesn't require extensive elaboration.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with both parameters (initiativeId, includeProjects) already documented clearly. The description adds no new meaning beyond the schema, merely reaffirming 'by ID' which the schema already states. The optional includeProjects flag is not highlighted in the description but is fully covered by the parameter description, so the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' with the resource 'initiative' and explicitly specifies 'by ID'. It unambiguously identifies the operation, distinguishing it from sibling tools like linear_getInitiatives (list) and linear_getInitiativeProjects (related projects). The purpose is precise and actionable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 doesn't mention when to choose this over linear_getInitiatives or linear_getInitiativeProjects, nor any context on prerequisites or use cases. The description is purely operational without situational direction, 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds no extra behavioral context beyond what is stated (e.g., no mention of not-found behavior, rate limits, or return format). Since annotations are present, the bar is lower, and the description is adequate but adds no additional value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no redundancy. It succinctly conveys the tool's purpose and identifier format with an example, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description is sufficient for an agent to understand what the tool does and how to call it. It lacks explicit alternative selection guidance, but that falls under usage guidelines. Otherwise, it is complete for this complexity level.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents the 'id' parameter with the same example 'ABC-123'. The description repeats this without adding new meaning, so it does not exceed the schema baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'a specific issue', with the identifier format 'ID or identifier (e.g., ABC-123)'. It is distinct from sibling tools like linear_getIssues (list) and linear_searchIssues (search) by specifying 'specific issue'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_searchIssues or linear_getIssues. It does not mention when to prefer this tool (e.g., when you already have an ID) or when not to use it. The name implies usage for known IDs, but this is not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds only the phrase 'currently set', implying it returns the current state rather than historical changes, which is minor additional context. No other behavioral traits (error handling, performance) are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with zero redundancy. The core action and resource are front-loaded, and every word is necessary. This is an exemplary model of brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (has output schema true), so return values are already defined structurally. The description sufficiently conveys the purpose and required input. However, given the large number of sibling tools, a hint about why one might choose this over linear_getCustomFields would enhance completeness, but it's not strictly necessary for a simple read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema fully describes the only parameter (issueId with example ABC-123) at 100% coverage. The description does not add any further meaning to the parameter beyond what the schema already provides. Since schema coverage is high, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get the custom field values that are currently set on a specific issue' clearly states a specific verb (Get), resource (custom field values), and scope (specific issue). It distinguishes from siblings like linear_getCustomFields (likely the field definitions) and linear_getIssueById (the issue object itself) by explicitly indicating it retrieves values for a particular issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention alternatives like linear_getCustomFields or linear_updateIssueCustomField, nor does it state conditions for selection. The agent must infer from the description alone, which is somewhat implied but not directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds no behavioral context beyond what the name and annotations imply—no notes on not-found behavior, response shape, or edge cases. This is acceptable for a simple get-by-id tool where annotations carry the burden, but the description itself contributes no additional behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tightly worded sentence with zero filler. Every word earns its place, and the key information (verb + resource) is front-loaded. For a one-parameter get-by-id tool, this is the ideal size.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the very low complexity (1 parameter, 100% schema coverage, output schema present, full annotation coverage), the description is nearly sufficient. The only real gap is the absence of sibling differentiation and usage guidance against linear_getIssueTemplates/getTeamTemplates, but the structured data carries enough weight that this is a minor omission rather than a critical hole.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%—the 'id' parameter is already documented as 'ID of the template to retrieve.' The description adds no semantic meaning beyond the schema, so the baseline of 3 applies. No compensation is needed, but none is offered either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Get details of a specific issue template.' The word 'specific' signals single-record retrieval by ID, which aligns with the tool name and distinguishes it from listing siblings like linear_getIssueTemplates and linear_getTeamTemplates. However, it does not explicitly differentiate from those siblings, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is only implied: a 'specific' template suggests 'use when you have a template ID and need its details,' which the 'id' parameter reinforces. There is no explicit guidance on when to choose this over linear_getIssueTemplates (list) or linear_getTeamTemplates, no exclusionary conditions, and no mention of alternatives. The intent is inferable but not stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose readOnly, idempotent, and non-destructive behavior, so the description does not need to repeat them. It adds no extra behavioral detail (e.g., pagination behavior or default includeCompleted), but remains consistent with annotations and provides a modest amount of context about filter capabilities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loads the primary action ('Get issues associated with a project'), and contains no superfluous wording. It is efficient and well structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with 9 parameters, a 100% schema coverage, an output schema, and annotations covering safety, the description covers the core purpose and filter categories. It omits explicit mention of defaults (limit, includeCompleted) and ordering, but those are documented in the schema. The only notable gap is explicit usage differentiation from sibling issue-retrieval tools, which is addressed under usage guidelines.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% — every parameter has a description. The description's mention of 'state, assignee, labels, cycle, and milestone' loosely maps to states, assigneeId, labelIds, cycleId, projectMilestoneId, but does not add syntax or semantics beyond what the schema already provides. Baseline 3 applies for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get'), a clear resource ('issues'), and a scoping noun ('project'), and enumerates filter dimensions (state, assignee, labels, cycle, milestone). It implies distinction from siblings like linear_getIssues by tying results to a project, but does not explicitly name an alternative.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for project-scoped issue retrieval and lists filter categories, giving an agent an idea of supported queries. However, it does not state when to prefer this over linear_getIssues or linear_searchIssues, nor does it mention the required projectId or any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds no behavioral context beyond what is implicit from the name and annotations. It does not describe pagination, ordering, or return format, but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence of only 6 words. No filler or redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists, the description does not need to explain return values. The description is sufficient for a straightforward retrieval tool, though it could hint at the nature of updates (e.g., timeline of text changes).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters having descriptions (limit with default, projectId with purpose). The description adds no additional meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get all updates associated with a project' clearly states the verb (Get), resource (updates), and scope (associated with a project). It distinguishes itself from siblings like getProjectUpdateById, createProjectUpdate, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 getProjectUpdateById for a single update, or when to use filtering vs pagination. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context (e.g., return format, auth needs) 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words. It is appropriately sized for a simple lookup tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with one parameter and an output schema (documenting return values), the description is sufficient. It covers the core action, though it could mention error conditions or the scope of details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% as the 'id' parameter is well-described inline. The description does not add further parameter semantics, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific release note' clearly states the action (Get details) and the resource (release note), and distinguishes it from siblings like linear_getReleaseNotes (likely a list) and other mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 vs alternatives like linear_getReleaseNotes or linear_searchReleases. The description assumes the agent knows to use it when an ID is known, but fails to articulate this or exclude other tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds no further behavioral details (e.g., what the count represents, whether limit affects it). It doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise at only four words. However, it sacrifices critical information about the parameter. While front-loaded, the brevity is not fully justified given the missing param explanation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The core action is simple and well-defined. Annotations and output schema (present but not shown) cover common concerns. The only gap is the undocumented parameter, but overall the description is largely sufficient for a basic count tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters1/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has a single parameter 'limit' (integer, minimum 1) with 0% schema description coverage. The description does not explain the purpose of 'limit' or how it affects the count. This leaves the agent to guess its semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Get count of unread notifications', which is a specific verb and resource. It distinctly differs from sibling tools like linear_getNotifications (which likely returns full notification objects) and linear_markNotificationAsRead.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when/when-not context, but the purpose is straightforward: use this tool when only the count is needed, not the full notification list. Alternatives are implied by sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds minimal behavioral context beyond the annotations (readOnlyHint=true, destructiveHint=false, idempotentHint=true) with the phrase 'ordinary workspace webhook'. While annotations already convey the safe read nature, the description does not provide additional details about response format, rate limits, or access requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that conveys the core functionality without extraneous words. It is appropriately front-loaded and concise, though it could be slightly expanded for clarity without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (get by ID) and the presence of an output schema, the description is complete enough for an agent to understand its purpose. However, it could benefit from clarifying what 'ordinary workspace webhook' means in contrast to other webhook types.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description mentions 'by ID' but does not explain what the 'id' parameter represents or how to obtain it. With 0% schema description coverage, the description should provide more context about the parameter's meaning, but it falls short.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'one ordinary workspace webhook', and the method 'by ID'. This distinguishes it from siblings like linear_getWebhooks (for listing all webhooks) and other webhook mutation tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool is for retrieving a specific webhook when you have its ID, but it does not explicitly state when to use this tool versus alternatives like linear_getWebhooks for listing or linear_getManagedOAuthApplicationById for other resources.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the write nature is disclosed. The description adds no extra context beyond 'Set', such as whether existing priority is overwritten or validation behavior. Given annotation coverage, this is acceptable but not enhanced.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with zero waste. It communicates the essential purpose without any filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity, an output schema exists, and annotations cover safety, the description is nearly complete. It could mention that the issue must exist, but that's implied. For a setter, this is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema fully documents both parameters, including the priority enum with meanings. The description adds no additional meaning beyond the schema, which is fine because coverage is 100%. Baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: 'Set the priority of an issue.' This clearly identifies the action and target, and is distinct from sibling tools like linear_updateIssue which covers multiple fields. No ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only states what it does, offering no guidance on when to use this tool versus alternatives (e.g., linear_updateIssue) or any exclusions. With dozens of issue-related tools, an agent would benefit from a note that this only changes priority, but it's absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with annotations (readOnlyHint=false, destructiveHint=false, idempotentHint=true). However, it adds no additional behavioral context beyond what annotations already provide, such as authentication requirements 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description consists of a single sentence with no wasted words. It is perfectly concise and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the low complexity (1 parameter, good schema coverage, annotations, and output schema), the brief description is nearly complete. It could mention that the action reverses an archive, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter 'id' is fully described in the input schema (100% coverage). The tool description does not add any further meaning or usage instructions beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Restore' and the resource 'archived customer need', making the action unambiguous. It distinguishes this tool from siblings like linear_archiveCustomerNeed and linear_deleteCustomerNeed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_archiveCustomerNeed. No prerequisites or exclusions are mentioned, leaving the agent 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds no further behavioral context beyond stating it is an unarchive operation. The agent can infer mutation from the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. 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.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (single required parameter, no nested objects, output schema exists), the description is largely complete. Could be improved by mentioning the return behavior or side effects, but not essential.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for stageId. The tool description does not add any additional meaning beyond the schema, meeting the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Unarchive a release stage' uses a specific verb ('Unarchive') and resource ('release stage'), clearly distinguishing it from sibling tools like linear_archiveReleaseStage.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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_archiveReleaseStage or linear_getReleaseStages. No prerequisites or context are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, providing safety profile. The description adds no extra behavioral context beyond 'Update', which is consistent but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence contains the essential information with no unnecessary words. It is as concise as possible while conveying purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of annotations and a full output schema, the description is sufficient for an update tool with few parameters. However, it does not mention required fields or common update patterns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All four parameters are described in the schema (100% coverage), and the description adds no additional meaning beyond what is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Update' and resource 'project update', clearly indicating the action and distinguishing it from siblings like create, archive, or get.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., create vs update, archive). The description only states what it does without contextualizing its role among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines2/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate a non-readOnly, non-destructive write operation. The description confirms a creation action but adds no further behavioral context (e.g., side effects, required permissions, or constraints). 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 9 words, front-loaded with the core action. Every word is necessary, and there is no redundant or irrelevant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters and an output schema, the description is minimal but sufficient. It does not discuss optional behaviors (e.g., backfilling timestamps) but the schema and output schema compensate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage across all 11 parameters. The description adds no parameter-specific information, but baseline is 3 given high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Create'), resource ('a new release'), and context ('in a release pipeline'). It distinguishes this tool from siblings like linear_getReleases, linear_searchReleases, etc.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use (creating a release), but lacks explicit guidance on when not to use or comparison with alternatives like linear_completeRelease or linear_updateRelease. No exclusions or context cues are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose destructive and idempotent behavior; the description adds no further behavioral context beyond repeating the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words; however, it could be slightly more informative without losing brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 an output schema, the description is adequately complete; it defines the action and required input without needing to detail return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the single parameter 'id' with a description; the description adds no additional parameter-level detail beyond the existing schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'delete', resource 'issue relation', and clarifies deletion by ID, which clearly distinguishes it from sibling tools that create or update relations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use vs alternatives; the context of deletion is implied by the verb 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=true, idempotentHint=true, destructiveHint=false. Description adds no further behavioral context (e.g., data freshness, authorization). Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence is efficient and front-loaded. Could be slightly more descriptive (e.g., noting output schema), but current length is appropriate for a simple get-by-ID tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with one parameter, good annotations, and an output schema. Description adequately states core purpose. Minor gap: no mention of return fields or typical usage context, but still sufficient for basic selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'id' is fully described in the schema as 'Customer need ID'. Description adds no extra meaning, but schema coverage is 100%, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a customer need by ID' clearly states the action (get) and resource (customer need) with the identifier (ID). It distinguishes this tool from siblings like linear_getCustomerNeeds (list) and linear_deleteCustomerNeed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage: use when you have a specific customer need ID. No explicit guidance on when to use vs. alternatives (e.g., linear_getCustomerNeeds) or when not to use. Lacks contextual hints about prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the tool's safety profile is clear. The description adds no further behavioral context (e.g., what entries are returned, ordering, limits). With annotations covering safety, the description adds minimal value here.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no waste. It is front-loaded and efficient, though it could be slightly more descriptive without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (context signals indicate 'Has output schema: true'), the description adequately indicates what the tool returns. For a simple read operation, it is complete, though it lacks notes on pagination or ordering.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the only parameter 'id' has a description 'Document content ID to inspect'. The description does not add any meaning beyond what the schema already provides, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get', the resource 'content history entries', and the scope 'for a Linear document content record'. It distinguishes itself from sibling tools like linear_getDocumentById or linear_getIssueHistory by focusing specifically on content history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when needing content history entries for a document, but provides no explicit guidance on when to use this tool versus alternatives such as linear_getDocumentById or linear_getIssueHistory. No exclusions or when-not-to-use are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is clear. The description adds no additional behavioral context (e.g., authentication needs, rate limits, or return value structure), which is acceptable given the annotations, but doesn't exceed the baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence (9 words) with no wasted words. It communicates the core purpose efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-by-ID tool with one parameter and an output schema, the description is complete. The output schema handles return details, so the description does not need to elaborate further.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema description coverage, the parameter 'id' is already documented as 'ID or slug of the project to retrieve'. The tool description adds no further meaning, so it meets the baseline but does not enhance clarity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get details') and resource ('specific Linear project by ID'), making the tool's purpose unambiguous and distinguishing it from sibling tools like linear_getProjects (which likely lists all projects).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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, when not to use it, or what alternatives exist (e.g., linear_getProjects for listing projects). It only states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds no behavioral traits beyond that, but it is consistent and does not contradict.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single concise sentence that communicates the core action without any unnecessary words. It is well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter tool with robust annotations and a complete output schema, the description is sufficient. It does not need to explain return values or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and parameters are well documented in the schema. The description does not add meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get members assigned to a project' uses a specific verb and resource, clearly distinguishing it from sibling tools like addProjectMember or removeProjectMember.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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 getUsers or getTeamMemberships, nor any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior2/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations fully cover the non-readonly nature; description adds the two creation modes but lacks further behavioral context like permissions or side effects. 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, front-loaded with purpose. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the two modes and mentions pipeline ownership. With output schema present (inferred), it provides sufficient context for a tool of moderate complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters have detailed schema descriptions (100% coverage), so the description adds only marginal value by summarizing the two modes. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (create), the object (release note), and the two methods (explicit IDs or range), distinguishing it from related tools like linear_getReleaseNotes and linear_updateReleaseNote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the two usage modes (explicit IDs vs range) but does not explicitly state when not to use this tool or mention alternatives like linear_updateReleaseNote for editing existing notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description does not add behavioral details like permissions or error behavior, but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with key information, no unnecessary words. Highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple retrieval tool with an output schema, the description adequately specifies the input. Could mention that it returns a full project update object, but the output schema covers that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter. The description's restatement of the parameter purpose adds no new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'Linear project update', clearly identifying the action and object. It distinguishes from sibling tools like linear_getProjectUpdates (list) and linear_deleteProjectUpdate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this vs alternatives. The name suggests retrieving a single update by ID, but the description does not provide context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the read-only safety profile is fully covered outside the description. The description adds no behavioral detail such as error behavior or included related objects, but none is required for this simple retrieval operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single clear sentence that immediately states action and target. No filler; the verb and resource are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With one documented parameter, a rich annotations block, and an output schema present, the description is sufficient for an agent to call the tool correctly. It could have pointed to linear_getRoadmaps for ID discovery, but that is not essential for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'id' parameter is already fully documented in the schema ('The ID of the roadmap to retrieve'), and schema coverage is 100%. The description adds little beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get details of a specific roadmap by ID' names the resource (roadmap) and the operation (get details), and the 'by ID' qualifier clearly separates it from list-style siblings like linear_getRoadmaps. An agent can tell this tool retrieves a single roadmap rather than enumerating all roadmaps.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use or alternative-tool guidance is provided; an agent must infer from 'by ID' that this is for retrieving one roadmap rather than listing all roadmaps. There are no prerequisites or exclusions stated, but the use case is strongly implied by the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds no further behavioral context such as pagination, return format, or authorization requirements, but for a simple list operation this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no filler. It is appropriately minimal for a parameterless list operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and an output schema that presumably defines the response, the description is sufficiently complete. It states the core operation without needing to specify filters or options. The only minor gap is not mentioning that it returns all teams, but that is implied by 'a list of teams'.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the baseline is 4. There is nothing for the description to elaborate beyond the schema, which already has 100% coverage (empty object).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get a list') and the resource ('teams from Linear'), making it unambiguous. It distinguishes itself from sibling tools like linear_getTeamLabels or linear_updateTeam by specifying it returns a list of teams.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
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. With a large sibling set including linear_getTeamMemberships, linear_getTeamDocuments, and linear_getTeams (if any variants existed), the description does not clarify context or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true, but the description adds no extra behavioral details such as what happens if the label isn't on the issue. With annotations present, the bar is lower; still, the description could mention idempotency 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence of 7 words, perfectly concise with no wasted text. Every word is necessary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple mutation tool with an output schema present, the description is adequate. It could mention return behavior or prerequisites, but overall completeness is high given the low complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions (100% coverage). Description adds no additional meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'remove', the object 'label', and the context 'from an issue in Linear'. It distinguishes from sibling 'add' tool without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use or when not to use this tool versus alternatives like adding labels or other issue modifications. The description is purely declarative without usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description adds minimal behavioral insight beyond annotations. Annotations indicate idempotent and non-destructive, but description doesn't clarify implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence, no wasted words, front-loaded with action and object.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple removal tool with full schema and output schema, description is adequate but could mention expected results or prerequisites.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers both parameters with descriptions; description adds no extra meaning. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action 'Remove' and the resource 'a member from a project', distinguishing it from sibling like linear_addProjectMember.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use versus alternatives, prerequisites, or error handling. Implied usage but lacks explicit context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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 safety profile. The description adds the field-change requirement but does not disclose additional behavior such as side effects, authentication needs, or edge cases (e.g., what happens with only id). It adds some value but not substantial behavioral context beyond annotations, and no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no redundancy. It states the purpose and the key usage requirement upfront, making it efficient and easy to parse. There is no wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 straightforward update semantics, the description is sufficient for an agent to invoke the tool correctly. It does not elaborate on complex behaviors like permission checks or null handling, but these are covered in the schema. The description adequately completes the picture for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so all parameter descriptions are already present. The description only adds the global requirement of providing at least one other field, which is a usage constraint rather than parameter-specific meaning. Per the baseline rule for high schema coverage, a score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update a Linear saved view' uses a specific verb and resource, clearly indicating a mutation operation. It also references the underlying API name (updateCustomView), and the operation is unambiguous compared to sibling tools like createSavedView, deleteSavedView, and getSavedViews.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a practical usage constraint: 'Provide id plus at least one other field to change.' However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions. The appropriate context is implied by the tool name, but there is no explicit routing to sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate a non-read-only, non-idempotent mutation, and the description adds that this operation creates a new roadmap rather than updating or deleting one. It does not disclose additional side effects such as permission requirements or duplicate-name behavior, but with annotations covering the basic safety profile this is adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler or redundancy. 'Create a new roadmap in Linear' is the minimal useful statement of the operation and every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple create operation with a full output schema and self-documenting parameters, the description is minimally sufficient. However, it does not distinguish a roadmap from conceptually similar Linear entities like projects, initiatives, or milestones, nor does it note potential prerequisites such as ownerId validation, so the agent must rely on the tool name and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented in the input schema. The description itself adds no parameter-level meaning, which 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.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action ('Create') and resource ('roadmap'), clearly distinguishing it from sibling tools like linear_updateRoadmap and linear_archiveRoadmap. The qualifier 'new' reinforces that this is the creation entry point rather than a read or modification operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies this tool is for creating a new roadmap, which is a distinct use case from the update, archive, and read siblings. It does not explicitly name alternatives or exclusion conditions, but the creation intent is unambiguous and provides clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, covering the safety profile. The description adds the notion of 'PM-friendly filters' but does not disclose additional behavioral traits such as default pagination or handling of missing cycles, which is acceptable given annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word adds value, clearly conveying the core function and key filters without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only operation with a full input schema (100% coverage) and an output schema, the description is sufficient. An agent has all necessary information to call the tool correctly without additional context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the description need not explain parameters further. It does add a brief semantic layer by listing filter types (state, assignee, labels, completion status), but this is largely redundant with the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('issues in a cycle'), distinguishing it from sibling tools like linear_getCycleById (cycle metadata) and linear_getIssues (all issues). The mention of filters like state, assignee, labels, and completion status further specifies its scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (cycle-specific issues) but provides no explicit guidance on when to prefer this over alternatives like linear_searchIssues or linear_getIssues. No exclusions or alternative tool names are mentioned, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is established. The description adds no additional behavioral context such as pagination behavior, filter semantics, or the fact that it returns a list. It does not contradict the annotations, but it also provides no extra value beyond the purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no unnecessary words. It is direct and efficient, fully earning its place without any fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that the output schema is present and annotations cover the safety profile, the description is sufficient for an agent to call the tool correctly. The required initiativeId is documented in the schema, filters are described, and the purpose is clear. No critical information is missing for this read operation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All five parameters are described in the input schema (100% coverage), so the description does not need to add parameter semantics. The description adds no information about parameters beyond what the schema already provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get'), a specific resource ('documents'), and the scope ('for a specific Linear initiative'). This distinguishes it from sibling tools like getProjectDocuments or getTeamDocuments by the initiative context, making its purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that the tool requires an initiative ID, but it does not explicitly state when to use this tool versus alternatives like getDocuments or getProjectDocuments. There is no mention of exclusions or the conditions under which another tool would be more appropriate, leaving the choice 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, fully covering the safety profile. The description adds nothing beyond the annotations — it only restates the read operation. Since there is no contradiction and the annotations carry the burden, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single declarative sentence with zero waste. Every word earns its place and the purpose is front-loaded. Nothing extraneous.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple list tool. The annotations carry the safety profile, the schema documents both parameters, an output schema exists, and the description states the scope precisely. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with both parameters (limit and includeArchived) fully documented in the input schema itself. The description adds no parameter-level detail, so per the baseline for high schema coverage, a 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('get'), a precise resource ('initiatives'), and a scope ('all'). The phrase clearly distinguishes it from siblings like getInitiativeById, createInitiative, archiveInitiative, and getInitiativeProjects. An agent can tell exactly what this tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit when-to-use guidance or exclusions are provided. For a straightforward list tool the usage is implied, and the siblings (getInitiativeById, createInitiative, etc.) make the alternative routes inferable, but the description leaves routing entirely to the agent rather than stating it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the description adds limited behavioral context beyond ownership scope. It does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundant words. Front-loads the main action and constraint. Perfectly concise for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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, read-only, output schema present), the description is nearly complete. It could mention the 'id' parameter but otherwise covers purpose and limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one 'id' parameter with no description, and the tool description does not explain the parameter's meaning. With 0% schema coverage, the description should compensate but does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb 'Get' and specifies 'alpha child OAuth application owned by the calling OAuth application', clearly distinguishing it from sibling tools like linear_getManagedOAuthApplications. It also explicitly states what it cannot do, removing ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states when to use the tool (retrieve a specific owned OAuth app) and when not (cannot retrieve arbitrary workspace OAuth app). While it implies alternatives, it does not explicitly name sibling tools for listing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the read-only nature is fully covered. The description adds no behavioral context beyond saying it 'gets details', such as access requirements or response behavior, but it does not contradict 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. Every word earns its place: it identifies the action, the resource, and the required input.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple, single-parameter read tool with full annotations and an output schema, the description is complete. Nothing an agent needs to invoke it correctly is missing; the output schema covers return values and the annotations cover safety semantics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes the single 'id' parameter with 100% coverage. The description's 'by ID' adds no additional meaning beyond what the schema provides, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get details'), a clear resource ('specific project milestone'), and the lookup mechanism ('by ID'). It is immediately distinguishable from sibling tools like linear_getMilestones (list all) and linear_updateMilestone/linear_archiveMilestone (mutations).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for retrieving a single milestone by ID, but it does not explicitly state when to prefer it over linear_getMilestones or mention any exclusions. Usage context is left to inference 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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds minimal behavioral context beyond this, such as the 'currently authenticated' nuance, but does not disclose any additional traits like auth requirements or rate limits. Since annotations carry the burden, a score of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb and resource. It contains no redundant information or filler, making it optimally sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a parameterless, read-only tool with an output schema, the description fully covers what an agent needs to know to call it correctly. There are no hidden parameters, side effects, or additional context required. The tool's complexity is low, and the description is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters and 100% schema coverage (vacuously), the baseline is 4. The description does not need to explain parameter semantics, and no additional meaning is required. The description is consistent with the empty input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb ('Get') and a precise resource ('information about the currently authenticated user'), making the tool's purpose unambiguous. It distinguishes itself from sibling tools that focus on other resources (teams, projects, issues) without needing further detail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or contrast with any sibling tool. While the purpose implies usage for retrieving the current user's profile, there is no explicit routing or comparative context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true, and the description's 'Restore' is consistent. However, it adds no further behavioral context beyond the action. No contradiction 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with no unnecessary words. It is appropriately front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple restore operation with one parameter and no complex behaviors, the description provides all necessary context. The presence of an output schema further reduces the need to explain return values.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'id' is fully described in the schema (100% coverage), and the description adds no additional meaning or format details. Baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Restore') and the resource ('archived Linear project update'), directly contrasting with sibling tools like linear_archiveProjectUpdate and linear_deleteProjectUpdate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when a project update is archived, but does not explicitly state when not to use it or mention alternatives (e.g., linear_archiveProjectUpdate for archiving). No guidance on prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description adds a requirement to provide at least one change field but does not disclose other behavioral traits like error conditions 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words. First sentence states purpose, second adds key usage condition. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Tool is simple with output schema present, but description lacks details about valid field combinations, edge cases (e.g., updating completedAt), and concurrency behavior. Could be more complete for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters with descriptions (100% coverage). The description adds a constraint beyond schema: you must provide at least one field to change, which is not enforced by 'required' in schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing cycle', which is a specific verb+resource combination. It distinguishes from sibling tools like linear_createCycle (create) and linear_completeCycle (complete).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description says 'Provide id plus at least one other field to change', which gives a usage constraint. However, it does not explicitly compare to alternatives or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent and non-destructive mutation. The description adds that it updates metadata/grants/webhooks but does not approve scopes, providing useful behavioral context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences that are efficient and front-loaded with key information. No redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness2/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For an 11-parameter tool with minimal schema descriptions, the description is too sparse. It omits parameter behavior details and does not leverage the existing output schema for completeness. The context provided is insufficient for accurate invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 9% (very low), and the general description does not detail any parameters. Parameter names are somewhat self-explanatory, but the description adds no additional meaning, failing to compensate for the low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates metadata, grant capabilities, or webhook configuration for a child app. It explicitly excludes granting token scopes, distinguishing it from related tools like create or rotate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It specifies the target (alpha child app owned by caller) and clarifies what it does not do (grant scopes). However, it lacks explicit alternatives or when-not-to-use guidance beyond the scope exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true. The description adds that the tool does not create the application and requires admin review, which aligns with read-only behavior. No contradictions. The description provides supplementary context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise—two sentences. It front-loads the main action and a critical caveat. Every word adds value, and there is no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness3/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 11 parameters, low schema coverage, and the presence of an output schema (not shown), the description lacks detail on how parameters affect the manifest or what the output contains. It covers the high-level flow but not enough to fully understand parameter usage without inspecting the schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters2/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 11 parameters with schema description coverage of only 9%. The tool description does not explain any parameter semantics or constraints. For example, the 'name' parameter has a pattern excluding 'Linear' or URLs, but this is only in the schema. The description adds no meaning beyond what the schema minimally provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Generate an official Linear OAuth application manifest and a human-confirmed setup URL.' It also explicitly distinguishes from related tools by noting 'This does not create the application,' which differentiates it from linear_createManagedOAuthApplication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it generates a setup URL that requires admin action. It implicitly tells when to use (to initiate OAuth setup) and when not to use (to finalize creation). However, it does not explicitly name alternative sibling tools for direct creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only and idempotent. The description adds critical context: scopes are merely requested, not persisted; and actor/scope compatibility rules. This goes beyond annotations without contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: clear purpose first, then behavioral details. No fluff; every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given an output schema exists (so return values are documented) and annotations provide safety profile, the description adequately covers scope behavior and actor rules. However, it omits usage of state and codeChallenge parameters, which are important for OAuth security.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is low (29%), but the description adds meaning by explaining scopes array constraints and actor enum impact. However, other parameters (codeChallenge, promptConsent, state) are not described, leaving gaps in understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with 'Generate a Linear OAuth authorization URL,' which is a specific verb-resource pair. It clearly distinguishes the tool's purpose from its siblings (e.g., linear_createOAuthClientCredentialsToken) by focusing on URL generation and explaining scope behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context on actor and scope constraints, which helps with correct invocation. However, it does not explicitly state when to use this tool over alternatives (e.g., linear_generateOAuthApplicationSetup for application setup). No when-not-to-use guidance is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral context such as default filtering of archived documents or pagination behavior, but given the simple read-only nature, a baseline score 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with no filler. Every word earns its place, conveying the verb, resource, and scope efficiently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and annotations covering safety, the description plus schema provides nearly everything needed for correct invocation. A minor gap is that 'associated' is not elaborated (e.g., linked vs. referenced documents), but the schema's limit/orderBy/includeArchived parameters cover the main call options.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all five parameters are already documented in the schema. The description does not add additional meaning beyond what the schema provides; it only restates the issueId scoping already present in the parameter description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') with a clear resource ('documents') and scope ('associated with a specific Linear issue'). This distinguishes it from sibling tools like linear_getDocuments, linear_getProjectDocuments, and linear_getTeamDocuments by explicitly scoping to an issue.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: use this tool when you need documents tied to a specific issue. It does not explicitly name alternatives or state when not to use it, but the scoping is unambiguous and the sibling names reinforce the distinction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint, idempotentHint, destructiveHint, covering safety and idempotency. Description adds behavioral context about ownership scope and CRUD limitations, which is valuable 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, efficiently front-loaded with core purpose, no unnecessary words. Perfect conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Has output schema, so return format is covered. Description gives purpose and scope, but 'alpha child' is not explained, which could leave ambiguity. Otherwise sufficient for a zero-parameter listing tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters (schema coverage 100%), so description does not need to add param info. Baseline 3 applies; no additional value provided or needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists 'alpha child OAuth applications owned by the calling OAuth application' and distinguishes itself from a workspace-wide listing and generic CRUD. The term 'alpha child' is somewhat ambiguous, lowering clarity slightly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states what it is not (workspace-wide admin listing, generic CRUD), guiding when not to use it. Does not name alternative tools but the exclusion is clear, and sibling getManagedOAuthApplicationById handles single retrieval.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, establishing the safe read-only nature. The description adds minimal extra behavioral context—the 'PM-friendly filters' is a minor feature note rather than a behavioral disclosure. The bar is lower due to annotations, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core action and resource, then immediately states the key value-add (filters). There is no filler or repetition; every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (per context signals), which covers return values. Parameters are fully described in the schema, and annotations cover the safety profile. The description lacks an explicit note about default exclusion of archived items (though includeArchived implies it), but this is a minor gap. The tool is well-specified for its simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all six parameters are well-documented in the schema itself. The description's mention of 'filters for project, team, and milestone status' loosely maps to projectId, teamId, and status parameters, but adds no new semantic detail beyond what the schema already provides. Baseline 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'project milestones from Linear', and highlights the key filtering capability with 'PM-friendly filters for project, team, and milestone status'. This makes the tool's purpose immediately apparent and distinguishes it from the sibling getMilestoneById which fetches a single milestone.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for listing milestones with filters, which is clear. However, it does not explicitly mention when NOT to use it (e.g., when you need a single milestone, use getMilestoneById). The guidance is inferred from the sibling list, but not explicitly stated in the description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with annotations (readOnlyHint, destructiveHint, idempotentHint) and adds no additional behavioral context beyond stating it gets information. Since annotations already cover safety and idempotency, the description does not need to elaborate further.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is concise, front-loaded, and contains no unnecessary words. It efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, rich annotations, and an output schema, the minimal description is adequate. However, it could briefly mention what kind of information (e.g., name, domain, settings) to improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description has no burden to explain them. The schema coverage is 100%, and the description correctly implies no inputs are needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and the resource ('information about the current Linear organization'). It distinguishes the tool from siblings like linear_getViewer or linear_getUsers by specifying the organization scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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, but the purpose is self-explanatory from the name and description. An implied usage context exists, but no explicit 'when not to use' or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotency and non-destructiveness. The description adds context that removal applies to the 'current user's favorites', which is not in the annotations. However, it does not disclose behavior when the favorite does not exist or when both IDs are provided.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. It efficiently conveys the action and parameter requirement.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
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 coverage, the description is largely complete. It covers the purpose and usage context. A mention of idempotency or result when favorite is missing could improve completeness, but the current level is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already describes both parameters with 100% coverage. The description adds minimal value by implying mutual exclusivity ('Provide either favoriteId or entityId'), which is not stated in the schema, but does not enhance meaning beyond that.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly specifies the action ('Remove'), the target (entity or favorite entry), and the scope (current user's Linear favorites). It distinguishes the tool from siblings like 'linear_addToFavorites' by indicating the opposite operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates that either 'favoriteId' or 'entityId' should be provided, but does not explicitly explain when to choose one over the other. It lacks guidance on when not to use this tool or mention of alternatives for managing favorites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true. The description adds that 'The new one-time secret is exposed in the MCP result', conveying its one-time nature and that the secret is returned. No contradiction 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, each carrying essential information: purpose and key behavioral note. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema (not shown) likely covering return value, the description adds that the secret is one-time. It doesn't mention prerequisites like ownership or impact on active webhooks, but given the destructive annotation, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50% (only confirmSecretExposure described). The description clarifies that confirmSecretExposure acknowledges the one-time secret return. For the id parameter, the description implies it is the child app's ID but does not explicitly describe it. Partial compensation for low coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Rotate' and the specific resource 'webhook signing secret of an alpha child app owned by the calling OAuth application'. This distinguishes it from siblings like linear_rotateManagedOAuthApplicationSecret (rotates app secret) and linear_rotateWebhookSecret (likely for non-child webhooks).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context (alpha child app owned by calling OAuth app) but does not explicitly state when to choose this tool over siblings like linear_rotateWebhookSecret or linear_rotateManagedOAuthApplicationSecret. No direct 'use this when' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=true), so the description is not burdened with that. It adds the 'at least one other field' constraint, which is a useful behavioral nuance. It does not disclose what happens to unspecified fields (assumed unchanged) or the response shape, but with idempotency and non-destructive hints in annotations, no significant gap remains and no contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence with zero wasted words: the verb and resource lead, followed by the one essential operation rule. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite being a 16-parameter tool, the description is adequate because the schema documents every parameter at 100% coverage, an output schema exists, and annotations cover idempotency and destructive behavior. The description adds the one key operational requirement (minimum-fields rule) the structured data cannot express. Only marginal behavioral color (e.g., unchanged-field semantics) is untold, which is minor given schema richness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
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 genuine value by stating that id alone is insufficient — at least one additional field must be supplied — a constraint not expressed in the schema (which marks only id as required). This clarifies a non-obvious calling requirement beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Update') and resource ('existing Linear document'), making the tool's function immediately clear. It implicitly distinguishes from linear_createDocument (new vs. existing) and from archive-style mutations like linear_archiveDocument/unarchiveDocument.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear precondition — 'Provide id plus at least one other field to change' — which tells the agent what is required to make a valid call. However, it offers no when-not-to-use guidance and does not route to any sibling alternative (e.g., linear_archiveDocument for trashing, or linear_updateIssue for issue updates), so differentiation from related mutation tools is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false, destructiveHint=false, and idempotentHint=true, so the description adds no extra behavioral context (e.g., side effects, permissions). It is consistent but not enriching, earning a baseline score.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no extraneous information. Every word is purposeful, achieving maximum conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists and annotations cover safety, the description is adequate for a straightforward update tool. It explains the core requirement. Missing nuance like partial updates is acceptable with schema coverage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the schema already documents each parameter. The description adds valuable constraint: 'Provide id plus at least one other field to change,' which is not in the schema. This goes beyond repetition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing release' with a specific verb and resource. It distinguishes from sibling tools like createRelease (no id) and archiveRelease (different operation).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when updating an existing release and explicitly requires providing id plus at least one other field. However, it does not compare to alternatives like archiveRelease or completeRelease, nor does it specify when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness3/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines3/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description does not add behavioral context beyond 'get', such as what happens if no active cycle exists (e.g., returns null) or any team-specific constraints. Given the annotations, the lack of additional detail is acceptable but not exemplary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that states exactly what the tool does without any filler or redundancy. It is appropriately sized for a simple getter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, single-parameter tool with a well-defined purpose and an output schema present, the description is complete. The agent has all necessary information to call the tool correctly: it needs a team ID, and the output schema details the response structure. Nothing essential is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter, teamId, is fully described in the schema with 'ID of the team to get the active cycle for', which gives 100% schema description coverage. The tool description adds no extra parameter semantics beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and the resource ('the currently active cycle for a team'), which is specific enough to distinguish from sibling tools like getCycles (list all cycles) or getCycleById (specific cycle). The word 'active' uniquely identifies the intended use case.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes it clear that this tool is for retrieving the active cycle for a team, which provides context on when to use it. It does not explicitly mention alternatives, but the phrasing 'currently active' implicitly sets it apart from listing or fetching by ID. No exclusions are stated, but the purpose is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint as false, covering the safety profile. The description adds no behavioral traits beyond the core operation (e.g., pagination, ordering, default archive exclusion). Since annotations handle safety, the description doesn't need to repeat it, but it also provides no extra behavioral context, so 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action and resource. It is extremely concise with no wasted words, making it easy for an agent to parse and understand.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list operation with a complete schema and an output schema present, the description covers all essential context. An agent knows exactly what to expect and how to invoke the tool correctly. No missing details deter correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema descriptions cover 100% of the parameters (initiativeId and includeArchived), so the baseline is 3. The description doesn't add any parameter-specific meaning or usage hints beyond the schema, so a score of 3 is correct.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and the resource ('all projects') scoped to 'an initiative', which distinguishes it from siblings like linear_getProjects (all projects) and linear_getProjectById (single project). It precisely conveys what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an initiative ID and need its associated projects, which is clear context. However, it does not explicitly mention when not to use it or name alternative tools, so it lacks explicit exclusion guidance. A score of 4 reflects the clear context but missing explicit alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering safety. The description adds no extra behavioral context (e.g., whether results are paginated or ordered), but does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is perfectly concise and front-loaded. Every word earns its place; no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero parameters, annotations covering safety, and an output schema (exists but not shown), the description is complete enough. It tells the agent exactly what the tool does without missing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the schema coverage is 100%. Following guidelines, zero parameters baseline is 4. The description adds no parameter info, but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get a list of projects from Linear' clearly states the verb (get) and resource (list of projects). It distinguishes from siblings like linear_getProjectById (single project) and linear_createProject (create), 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.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives (e.g., linear_getProjectById for a specific project). For a zero-param list tool, usage is somewhat implied, but no exclusions or context are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context such as pagination behavior, error handling, or side effects beyond the obvious read operation. It provides minimal extra value beyond what annotations and the schema 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear, and direct sentence with no unnecessary words. It is appropriately sized for the simple purpose and front-loads the key action and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a straightforward read operation with a fully described schema and an output schema present, the description is complete. It states the scope (release documents), and the annotations cover safety. Nothing essential an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All 5 parameters are fully documented in the schema (100% coverage), so the description does not need to explain them. The description adds no extra meaning beyond what the schema provides, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), resource ('documents'), and scope ('associated with a specific Linear release'). This clearly distinguishes it from sibling tools like linear_getProjectDocuments or linear_getDocuments, leaving no ambiguity about what the tool retrieves.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context by specifying the scope (documents associated with a release), implying when to use this tool. However, it does not explicitly name alternatives or state when not to use it, so it lacks explicit exclusions but the context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, providing the safety profile. The description does not add extra behavioral context beyond what annotations provide, so it meets the baseline but adds no additional value.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no wasted words. It is front-loaded and efficiently communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of a full output schema and comprehensive annotations, the description is complete for a simple get-by-id tool. No additional information is needed for an AI agent to correctly select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameter descriptions, so the description does not need to compensate. The description adds no extra meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'release pipeline', clearly stating the tool's function. It distinguishes from sibling tools like linear_getReleasePipelines (list all) and linear_createReleasePipeline (create), 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.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description lacks explicit guidance on when to use this tool versus alternatives, the naming convention and sibling list imply its use for retrieving a single pipeline by ID. The context is clear but falls short of explicit when-not or alternative references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety is covered. The description adds only the API type (CustomView), which is minor contextual information but does not contradict annotations. It doesn't describe return format or pagination, but the output schema handles that.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler, front-loaded with the action. Every word earns its place, and it conveys the essential purpose immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only list operation with an output schema present, all parameters are optional and documented in the schema, and annotations cover the safety profile. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter (limit, orderBy, includeArchived) having a description. The tool description adds no parameter-specific meaning beyond the schema, so it hits the baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'saved views', with an API reference to 'CustomView'. It differentiates from create/update/delete siblings, and the singular focus on retrieval is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the tool for listing saved views, and sibling names like createSavedView/updateSavedView/deleteSavedView make the contrast clear. However, it doesn't explicitly exclude favorites (getFavoriteViews) or provide conditions for when to prefer this over alternatives, though the sibling set covers that.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is covered. The description adds useful context about the type of data returned (runtime status, counts, rate-limit snapshot), which goes beyond the annotations, but does not elaborate on specifics like response format or pagination. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that immediately states the purpose and key data returned. It is front-loaded and contains no filler, making it easy to parse for an agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, an output schema (per context), and safe annotations, the description adequately covers what the tool does and what it returns. No critical information is missing for an agent to decide whether to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline is 4. The description does not need to explain parameters, and the schema is effectively empty. This is appropriate for a no-argument status check.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches MCP Linear server runtime status, counts, and a rate-limit snapshot. It uses a specific verb ('Get') and resource ('server status'), and distinguishes from the sibling linear_getRateLimitStatus by including additional 'counts' and 'runtime' context, making its broader scope evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (when server status or rate-limit snapshot is needed) but does not explicitly state when to prefer linear_getRateLimitStatus for rate-limit-only queries. No exclusions or explicit alternative guidance is provided, leaving the agent to infer based on the overlap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint=true, idempotentHint=true, destructiveHint=false) already cover the safety profile. The description adds no additional behavioral context such as pagination, rate limits, or return-value structure. Since this is a read-only operation with an output schema, the lack of extra detail is acceptable, but the description itself does not enrich 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It efficiently conveys the core action and scope. Every word earns its place, exemplifying concise structuring.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only list tool with an output schema and safety annotations, the description is fully complete. It answers what the tool does, and the output schema handles the return description. There is no missing information an agent would need to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema trivially covers them. Per the baseline rule for 0 params, a score of 4 applies. The description adds no parameter-specific meaning because none exist, and that is appropriate; nothing is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get') and resource ('list of users') with scope ('in the Linear organization'). This clearly distinguishes it from siblings like getViewer (current user) and getOrganization (org metadata), allowing an agent to select it appropriately without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives such as getViewer or getOrganization. The purpose is clear enough that usage is implied, but no alternatives or exclusion criteria are mentioned, leaving room for an agent to guess about edge cases (e.g., 'when you need all users, not just yourself').
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotentHint=true and destructiveHint=false. The description 'Restore' aligns with these, adding no additional behavioral context beyond what annotations provide. With annotations covering safety, a score of 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 5 words, highly concise and front-loaded. Every word is necessary and there is no extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one parameter and an output schema exists. The description fully covers the action needed for an agent to decide to use it, with no missing context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters3/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has one parameter 'id' with a description. Schema coverage is 100%, so the description adds no extra meaning beyond what is already in the schema. Baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Restore a previously archived Linear document' clearly uses the verb 'Restore' which matches the tool name 'unarchive', and identifies the resource as 'Linear document'. It distinguishes itself from sibling tools like linear_archiveDocument.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies that this tool is used to undo an archive operation, but it does not explicitly state when to use it versus alternatives. However, given the straightforward inverse relationship with linear_archiveDocument, the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness4/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare destructiveHint=true and idempotentHint=true. The description adds specificity by stating that only 'other' sessions are revoked, which is beyond the annotations. However, it does not mention that the current session remains intact.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, using a single phrase with no unnecessary words. It is front-loaded with the action and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter tool with output schema and clear annotations, the description is adequately complete. It clearly states the action, though it could mention that the current session is not affected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist, so the description is not required to explain them. Baseline of 4 applies as per guidelines for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Revoke all other sessions' clearly states the action and resource, and distinguishes itself from sibling tools like 'linear_logoutSession' and 'linear_logoutAllSessions' by implying it affects only other sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
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 'linear_logoutSession' or 'linear_logoutAllSessions'. The description only states the action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, so the description's update semantics are consistent. The description adds the requirement of at least one change field but does not elaborate on side effects or authorization. This is adequate but not exceptional.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 12 words, front-loading the action. It is highly concise without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema (not shown) so return values need not be explained. The description covers the essential behavior. It could mention when to use this tool versus create/archive/deletion but the sibling names provide context. Slightly incomplete but functional.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds the rule that at least one non-id field must be provided, which is not in the schema's required list. This additional constraint improves semantic understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing release stage' clearly specifies the action (update) and resource (release stage). Among siblings like linear_updateRelease and linear_updateReleasePipeline, it uniquely identifies this tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear guideline: 'Provide id plus at least one other field to change.' This tells the agent the minimum input needed. It lacks explicit when-not-to-use or alternatives, but the guideline is valuable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters3/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already disclose that the tool is read-only, idempotent, and non-destructive. The description adds no additional behavioral context beyond what annotations provide, meeting the expected baseline.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, short sentence that conveys the tool's purpose without any extraneous words. It is optimally concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (no parameters, with annotations and an output schema), the description is complete. It explains the tool's function adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters (schema coverage 100%), so the description bears no burden for explaining parameters. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves 'active authentication sessions', specifying a distinct verb and resource. It is easily distinguished from sibling tools like logoutSession, which perform different operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use to view sessions. While no explicit alternatives or exclusions are given, the tool's purpose is straightforward and distinct from its siblings, making usage unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare the tool as readOnly, idempotent, and non-destructive. The description adds useful context by specifying the exact resource (rate-limit cooldown and retry snapshot), which is additional to annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence of 11 words, no filler, and effectively communicates the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple getter with no parameters and existing output schema, the description is complete. It covers the resource type and is supported by annotations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and schema description coverage is 100%, so baseline is 4. The description does not need to add parameter details, as there are none.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves a rate-limit status snapshot, using a specific verb and resource. It distinguishes itself from sibling tools like getServerStatus by focusing on rate-limit cooldown and retry.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines3/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when rate-limit information is needed, but provides no explicit guidance on when to use this versus alternatives such as getServerStatus. No exclusions or alternatives are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already convey non-read-only, non-destructive, idempotent behavior. The description adds that an update requires a value to change beyond the id, but does not discuss validation, auth, 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.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence with no filler; the core requirement is front-loaded and immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple update operation, the description, full schema coverage, and annotations provide everything needed to invoke it correctly. The output schema covers return values, so no further description is required.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema documents all parameters at 100% coverage, so the baseline is 3. The description adds the meaningful constraint that calling with only id is insufficient, which is not visible in the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Update') and resource ('existing project milestone'), making the tool's action unambiguous. It is clearly distinct from sibling tools like linear_createMilestone or linear_archiveMilestone because it says 'existing' and 'to change'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives a clear usage rule: provide id plus at least one other field to change. It does not explicitly name alternatives or exclusions, but the rule is enough to avoid invalid calls.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations indicate idempotent, non-destructive. Description adds behavioral nuance: you must provide id plus at least one other field. No contradictions with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, 27 words. Direct, no fluff, front-loaded with the action. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, annotations, and output schema, the description covers the main invocation patterns and a key constraint. It doesn't explain conflicts if both releaseIds and range are provided, but it's sufficient for correct use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description adds meaning by explaining the two usage patterns (explicit IDs vs range) and the requirement to provide at least one additional parameter, which complements the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Update a release note') and distinguishes between two ways to specify releases (explicit IDs or range). This differentiates it from siblings like createReleaseNote or deleteReleaseNote.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context: 'Update a release note' and a key requirement ('Provide id plus at least one other field to change'). It does not explicitly exclude cases, but the purpose is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false. Description adds behavioral constraint that at least one other field must be provided, which is useful. No contradiction with annotations. Could have mentioned idempotency explicitly but annotations cover it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no unnecessary words. Information is front-loaded: the core action and a key constraint are stated immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With full schema coverage, annotations, and output schema present, the description adequately covers the essentials. It could mention idempotency or return value details, but these are covered by annotations and output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds the requirement that at least one field besides id must be changed, which adds meaning beyond the schema. This guideline is not apparent from schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Update' and resource 'release pipeline'. Distinguishes from siblings like linear_updateRoadmap by specifying the exact resource. The requirement 'Provide id plus at least one other field' further clarifies purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states the requirement that id plus at least one other field must be provided. This is a clear usage guideline. Does not explicitly contrast with alternatives, but the context of sibling tools (e.g., linear_archiveReleasePipeline) makes it implicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Behavior5/5
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.
Conciseness5/5
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.
Completeness5/5
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.
Parameters4/5
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.
Purpose5/5
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.
Usage Guidelines4/5
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.
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses critical behavioral traits beyond annotations: the new one-time secret is exposed in the result, and existing client-credentials tokens may be invalidated. This adds value over the destructiveHint annotation and warns the agent about consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences long, front-loading the action and resource, then adding important consequences. No unnecessary words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has two parameters, an output schema, and involves security implications, the description covers the essential points: what is rotated, who owns it, the secret exposure, and potential token invalidation. It is complete for an agent to invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds context for the `id` parameter by implying it identifies the alpha child app, which is not detailed in the schema. The `confirmSecretExposure` parameter is well-described in the schema, and the tool description reinforces its purpose. With 50% schema description coverage, the description compensates sufficiently.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Rotate the client secret of an alpha child app owned by the calling OAuth application.' This is a specific verb (rotate) and resource (client secret), and it is easily distinguished from sibling tools that rotate webhook secrets or other types of secrets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use this tool (to rotate a client secret for an alpha child app) but does not explicitly state when not to use it or contrast it with alternatives like rotaryManagedOAuthApplicationWebhookSecret. However, given the clear resource distinction, it provides sufficient context for an agent to choose correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

GitHub Badge

Glama performs regular codebase and documentation scans to:

Confirm that the MCP server is working as expected.
Confirm that there are no obvious security issues.
Evaluate tool definition quality.

Our badge communicates server capabilities, safety, and installation instructions.

Card Badge

Copy to your README.md:

[![mcp-linear MCP server](https://glama.ai/mcp/servers/tacticlaunch/mcp-linear/badges/card.svg)](https://glama.ai/mcp/servers/tacticlaunch/mcp-linear)

Score Badge

Copy to your README.md:

[![mcp-linear MCP server](https://glama.ai/mcp/servers/tacticlaunch/mcp-linear/badges/score.svg)](https://glama.ai/mcp/servers/tacticlaunch/mcp-linear)

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tacticlaunch/mcp-linear'

If you have feedback or need assistance with the MCP directory API, please join our Discord server