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 the temporal scoping ('since your claim') and the diff output shape. However, it doesn't say what happens when no claim exists or what the diff looks like in edge cases, leaving gaps beyond the 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.

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

Two short sentences with zero filler; the core behavior and the invocation trigger are both front-loaded. Every sentence earns its place.

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

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

With rich annotations, a fully documented parameter, and an existing output schema, the description covers what the tool does and when to call it. Only minor edge-case behavior (no prior claim, empty diff) is missing, which 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.

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

Schema description coverage is 100% and the single `issue` parameter is fully documented in the schema with a format example (ENG-123 or UUID). The description adds nothing parameter-specific, so the baseline 3 applies.

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

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

The description states a specific check: whether the ticket description changed since the caller's claim, plus a line diff of the change. It's phrased as a question rather than a verb+resource statement, but an agent can identify the operation. It relates to the `claim` and `description_history` siblings without explicitly distinguishing itself from them.

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

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

Explicit timing guidance: 'Run before opening or merging a PR for the ticket.' This gives clear context for invocation. It does not name alternatives (e.g., description_history) or state when not to use it, so it falls short of a 5.

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

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

Annotations flag it as destructive, non-read-only and non-idempotent, and the description adds substantial context beyond them: the refusal rule for other agents, the identity-dependent assignee/delegate behavior, and that re-claiming after a change is an acknowledgement act. These are behavioral traits the annotations cannot convey.

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

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

Three tightly packed sentences that lead with the core action and effect, then the routing rules, then the re-claim case. Dense but every clause carries information; no filler.

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

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

An output schema exists so return values need not be described. Combined with the annotations, the description covers identity semantics, refusal conditions, and the acknowledgement workflow, leaving no significant gap for correct invocation.

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

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

Schema coverage is already 100%, so the schema baseline is 3; the description adds meaning by explaining the automatic assignee/delegate choice that the 'as' override modifies, and reinforcing the take_over restriction. It goes beyond restating the schema, though it does not detail format for 'issue'.

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

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

It states a specific verb and resource ('Take a ticket and record the description as it stands') and immediately differentiates the action from its sibling check_claim by explaining the later Done check that consumes the record. An agent can tell what this 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.

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

Explicit about when it applies (assignee when unowned, delegate when a human owns and you are an app identity), when it refuses (a ticket held by another agent), and the re-claim workflow as acknowledgement. This is when/when-not guidance rather than implied usage.

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

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

Annotations declare a destructive, non-idempotent write, and the description adds rich behavioral detail beyond that: base is a stale-write guard that refuses with a diff, answer flips a row to ANSWERED with a link, closed_by sets a Linear relation and records under Fix. This is substantive disclosure for a mutation tool.

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

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

Front-loads the core action and then organizes by kind labels, with no filler. The single dense paragraph is slightly hard to scan for 10 parameters, but every sentence carries necessary information.

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

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

With an output schema present and annotations covering the safety profile, the description need not explain returns. It covers kind semantics, patch requirements, base staleness handling, and cross-tool routing, which is complete for this tool's complexity.

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

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

Schema description coverage is 90%, so the schema already documents most parameters. The description still adds conditional meaning, such as correction requiring the description patch and answer requiring the question id, but much of it overlaps with the schema's own per-field descriptions. A 4 reflects modest added value over a very complete schema.

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

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

States a specific verb and resource ('Post a typed comment') and then enumerates the five comment kinds with their distinct purposes. It also explicitly distinguishes itself from set_status, so an agent can route correctly without opening schemas.

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

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

Gives per-kind usage conditions: evidence for findings, correction for description patches, ask/answer for the open-questions row, closed_by for work landed elsewhere. It names the alternative for state changes ('Move the state separately with set_status'), which is explicit when-not guidance.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false. The description adds genuinely useful behavior beyond that: sections are validated the same way set_state validates them, and the ticket "starts in the form every other tool expects," which tells the agent the creation guarantees a canonical shape. It does not cover permissions or failure modes, so not a 5.

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

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

Three sentences, front-loaded with the core action, then the section model, then the conditional Done-when rule. No waste or repetition.

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

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

Output schema exists, so return values need not be explained. Annotations cover the safety profile. The description supplies the key cross-tool behavioral contract (section validation parity, canonical form) but leaves minor gaps such as the Impact section mentioned only in the schema and no note on team/title requirements.

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

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

Schema coverage is 60%, so the schema already documents team, parent, sections (with detailed formatting rules) and project_id, leaving title and project_id thinner. The description reinforces the section model and its relationship to set_state, but omits the Impact section and adds no syntax beyond what the schema states. Baseline 3 is appropriate.

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

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

Starts with a specific verb+resource ("Create a ticket"), so the agent immediately knows the operation. It also references sibling tools (set_state, set_status) to explain how the created ticket behaves, though it doesn't contrast with other creation-adjacent siblings. Clear, with partial sibling context.

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

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

Gives one conditional rule: include a Done when section if the ticket will be closed via set_status. That is useful context but is guidance about a section rather than when to choose create_issue itself. No exclusions or alternative-selection guidance.

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

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

Annotations already declare the safe read-only, idempotent, non-destructive profile, so the bar is lower. The description adds behavioral context beyond annotations by explaining snapshots, line diffs against the previous version, what `current` means, and how blame attributes each line to a version and author.

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

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

The description is front-loaded with a clear definition and proceeds logically through return semantics, blame behavior, and usage. It is appropriately sized for a tool with an output schema, though the `current` and `blame` sentences overlap somewhat with structured documentation.

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

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

With annotations covering safety and an output schema covering return fields, the description supplies all remaining context an agent needs: what the tool retrieves, what blame does, and when to reach for it. Nothing essential for correct invocation is missing.

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

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

Schema description coverage is 100%, so the schema already documents both parameters, establishing a baseline of 3. The description elaborates on the `blame` effect and mentions `current`, but adds little syntax or meaning beyond what the schema already provides for `issue` and `blame`.

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

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

The description clearly states the resource: past versions of a description, with when, by whom, and line diffs. It is specific about what the tool returns, though it does not explicitly differentiate itself from sibling tools like get_issue or comment.

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

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

It explicitly says when to use it: to see when and by whom a section or tick changed before overwriting or disputing it. No alternative tools or when-not conditions are named, so it stops short of full routing guidance.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered. The description goes further by disclosing retrieval behavior (all comment pages, oldest-first) and the semantics of derived fields like `omitted` and `drift.unreconciled_comments`, plus the repair workflow for tickets edited by other clients. Return format details are partly duplicated by the output schema, but the drift semantics are genuinely additive.

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

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

Purpose is front-loaded in the first clause, and every subsequent sentence carries substantive meaning for a tool with this many return structures. The middle sentences are dense run-ons packing several field semantics together, which costs a little readability but not enough to call it bloated.

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

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

With an output schema present, the description does not need to spell out every returned field, and it correctly focuses on interpretation (omitted, findings, drift) and the reconcile-first workflow. An agent has enough to call the tool and act on results, though the relationship to description_history for non-full reads is left unstated.

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

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

Schema coverage is 100% with a single parameter already documented in-schema as 'Issue identifier (e.g. ENG-123) or UUID'. The description adds no syntax or format nuance for `issue` itself (description_sha is a field of the ticket, not the argument), so the baseline of 3 for high-coverage schemas applies.

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

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

The description opens with a specific verb+resource ('Read one ticket whole') and enumerates exactly what is retrieved: description, comments oldest-first across all pages, editors, relations, children, attachments. This clearly separates it from list_issues (multiple tickets) and comment (writes) among the siblings.

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

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

It gives concrete follow-up guidance: when drift.needs_reconcile is true, fold the flagged comments into the description via set_state using reconciled_through, and pass issue.description_sha as the base for the description patch. That names the alternative tool and the triggering condition, though it never explicitly says when to prefer get_issue over description_history.

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

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

Annotations already establish readOnly, idempotent, non-destructive, and non-open-world behavior, so the safety profile is covered. The description adds genuinely useful behavior the annotations cannot convey: results are ordered earliest-first and the default window is the active and next cycle.

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

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

Two short sentences, zero filler, with ordering and default scope front-loaded ahead of the cross-reference. Every clause carries information an agent can act on.

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

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

An output schema exists, so the description need not explain return values, and the annotations cover safety. What remains is ordering and default scope, both stated; only a brief note on pagination or team-scoping behavior is absent, which is minor.

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

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

Schema description coverage is 100%, so both the team key and the when enum are fully documented in the schema; the description restates the default value ('active and next cycle') without adding format or syntax detail. The reference to a 'cycle number' describes a list_issues parameter rather than this tool's own inputs, so there is no real gain over the schema.

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

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

The fragment 'Cycles, earliest first' names the resource and its ordering, and the follow-up sentence clarifies scope by noting the default of active-plus-next cycles. The verb is only implied (list), but the content is specific enough to separate it from list_issues, list_teams, and other siblings.

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

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

It states the default scope and explicitly routes the agent to list_issues with a cycle number plus team to see a cycle's tickets, which is a concrete handoff condition. It does not state when-not to use this tool or contrast it with other listing tools, so it falls short of full when/when-not coverage.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so the safety burden is lifted. The description adds a real behavioral fact not in the annotations: the default result set silently excludes completed initiatives unless include_closed is set. That is the kind of default-behavior disclosure that prevents miscalls.

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

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

Two short, front-loaded sentences with no filler. Slightly telegraphic ('Initiatives with status, owner and target date' reads as a fragment), but every clause carries information.

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

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

With an output schema present, return values need no explanation, and annotations cover the safety profile. The description supplies the only missing piece an agent needs — the default filtering behavior — so it is essentially complete for a one-parameter list tool.

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

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

Schema coverage is 100% and the single parameter's description ('Include completed initiatives') is already documented structurally. The description reinforces the include_closed semantics by stating the default filter, but adds no format or edge-case detail beyond the schema.

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

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

Names the resource (initiatives) and the fields it surfaces (status, owner, target date), so the agent knows what listing this returns. It does not differentiate from the many list_* siblings (list_issues, list_projects, list_cycles, list_teams), but the resource itself is unambiguous.

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

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

The second sentence defines the default scope ('Unfinished ones only unless include_closed'), which is genuinely useful selection guidance. However, there is no statement of when to prefer this tool over alternatives or any prerequisite context.

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

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

Annotations cover the safety profile, but the description adds substantial non-obvious behavior: server-side pagination to completion, a hard refusal above 2000 matches, and the exact row columns returned. These are operational traits the annotations cannot express.

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

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

Three dense sentences, front-loaded with scope, then return shape, then constraints and routing. No filler; every clause carries information (cap, pagination, columns, alternative tool).

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

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

Even though an output schema exists, the description clarifies what the rows actually contain and the failure mode at 2000 matches. Combined with annotations and schema, an agent has everything needed to call and interpret this tool correctly.

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

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

Schema description coverage is 75%, so the schema already documents most params. The description enumerates the narrowing filters, which adds modest signal about which params constrain the result set, but does not add format or syntax detail 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.

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

States a specific verb+resource ('Every ticket matching the filters, in one call') and distinguishes itself from get_issue by noting rows hold no description excerpts. An agent can tell what it returns and how it differs from the sibling detail tool 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.

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

Explicitly routes the agent: 'read a ticket with get_issue before acting on it', and 'narrow with open, state, cycle, project, assignee_is_me or delegate_is_me' when matches exceed 2000. Also names the use case 'when a task covers a set, work every row'. Covers when-to-use, when-not (too broad), and the alternative.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds non-obvious behavior beyond that: results are filtered to open projects by default, which an agent would not know from the schema alone. It does not mention any pagination or result-limit behavior, keeping it short of a 5.

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

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

Two short sentences, no filler, with the returned-field summary front-loaded and the filtering caveat placed last where it is actionable. Nothing here is wasted or redundant.

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

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

With an output schema present, the description need not explain return values, and it correctly covers the default filtering behavior for a simple two-parameter read tool. The only mild gap is the team scoping parameter, which is left entirely to the schema.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (team key, include_closed flag), making 3 the baseline. The description restates include_closed's semantics ('Open projects only unless include_closed') but says nothing about the team parameter's scoping behavior, so it adds little beyond the schema.

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

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

The description names the resource (projects) and enumerates the returned fields (status, lead, teams, dates, progress), which combined with the tool name 'list_projects' makes the operation unambiguous. It is distinguishable from sibling list_* tools (list_teams, list_issues, list_cycles), though it never states the verb explicitly and reads as a field listing rather than an action.

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

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

The clause 'Open projects only unless include_closed' tells the agent when the default behavior applies and how to widen it, which is real usage guidance. However, no alternatives are named and there is no statement about when to prefer this tool over, say, list_issues or list_cycles when scoping a query.

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

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

Annotations already establish readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuinely useful context beyond them: entries are returned in board order and the returned state names are the valid inputs for set_status, which is a cross-tool contract not captured anywhere in 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.

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

Two short, declarative sentences with no filler, and the content description is front-loaded before the set_status cross-reference. Every sentence carries information an agent can act on.

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

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

With an output schema present, the description is not obliged to detail return values, and the annotations cover the safety profile. The set_status linkage supplies the main missing rationale for calling it, leaving little an agent needs that is absent.

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

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

The tool takes zero parameters, so the baseline of 4 applies; there is nothing for the description to disambiguate. Schema coverage is reported at 100% with an empty property set, leaving no semantic gap to fill.

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

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

States a specific resource (teams) and enumerates what each entry contains (key plus workflow states in board order), so an agent knows exactly what comes back. It does not explicitly distinguish itself from sibling list tools like list_projects or list_cycles, but the resource naming makes the boundary self-evident.

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

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

Usage is implied rather than stated: by noting that 'state names are what set_status takes,' it signals this is the lookup to run before calling set_status. There is no explicit when-to-use or when-not-to-use framing and no named alternative to prefer in other situations.

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

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

Annotations already declare idempotentHint=true, destructiveHint=false and readOnlyHint=false, so the safety and repeatability profile is covered. 'Reports each id separately' hints at per-id outcome reporting, but with an output schema present that detail is already documented structurally, so the description adds only modest value.

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

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

Two short sentences, zero filler, with the action and the timing cue front-loaded ahead of the reporting note.

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

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

For a single-required-param tool with full schema coverage, annotations, and an output schema, the description covers the intent and the per-id reporting behavior. It is complete enough to invoke correctly, though it could say more about bulk failure handling.

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

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

Schema coverage is 100% and the single 'ids' array parameter is fully described in the schema as 'Ids from notifications'. The description adds no syntax, ordering, or batch-limit meaning beyond that, so baseline 3 applies.

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

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

States a specific verb+resource ('mark notifications read') and scopes it with 'once you have handled them'. It is clearly distinguishable from the read-oriented sibling 'notifications', though it never names or contrasts with a sibling explicitly.

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

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

The phrase 'once you have handled them' gives an implied precondition for use, but there is no when-not guidance and no mention of alternatives such as the 'notifications' listing tool. Adequate but leaves routing to inference.

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

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

Annotations already declare a safe, idempotent read, so the bar is lower, yet the description adds real value: excerpt text is deliberately omitted, so a follow-up get_issue call is required before acting, and unread-only filtering is the default. It doesn't mention rate limits or the notification-type vocabulary, but the behavioral caveat it does give is the one an agent would otherwise get wrong.

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

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

Three short sentences, front-loaded with what the tool is, then the critical caveat, then defaults. No sentence is filler; each carries a distinct fact.

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

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

An output schema exists, so return values need no explanation, and the description still covers the three things an agent needs: the pointer-only return shape, the pre-action read requirement, and pagination/default filtering. Nothing required to call it correctly is absent.

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

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

Schema coverage is 100%, so 'unread_only' default true and cursor paging are already documented in the schema; the description only restates them at a high level. Baseline 3 is appropriate — no new syntax, format, or constraint meaning is added.

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

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

States a specific resource ('Your Linear inbox') plus ordering ('newest first') and the exact shape of each row (ticket, notification type, actor, timestamp). An agent can distinguish it from sibling list tools like list_issues and from the mutating mark_notifications_read without opening any schema.

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

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

Explicitly routes the agent onward ('read the ticket with get_issue before acting') and states the default filter and paging behavior. What's missing is a direct comparison point against mark_notifications_read or list_issues, but the when-to-use context is otherwise clear.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the mutation profile is known. The description adds genuinely useful behavior beyond that: all-or-nothing atomicity (names resolved first, whole call refused if any is unknown or ambiguous) and the permission rule that reassigning a person's ticket requires take_over.

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

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

Three sentences, each front-loaded and load-bearing: field scope, sibling routing, atomicity, then permission rules. Dense but no filler sentences; the field enumeration is the longest part but earns its place by scoping the tool.

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

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

With an output schema present, return values need not be explained. For a 17-parameter mutation tool the description covers scope, atomicity, and permission gates well; only minor gaps remain (e.g., whether omitted fields are left untouched).

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

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

Schema description coverage is 82%, so the schema carries most parameter meaning (baseline 3). The description supplements this by grouping the mutable fields and clarifying the take_over requirement and the assignee-refusal rule, adding semantics the schema cannot express.

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

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

States a specific verb (change) and resource (ticket fields) and immediately enumerates the field categories it covers, while explicitly excluding content and workflow state. It names the sibling tools that own those exclusions (set_state, set_status), so an agent can distinguish it without opening any schema.

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

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

Routes the agent to alternatives with conditions: description changes go through set_state and workflow state through set_status. It also gives a clear precondition for the take_over flag and states that another agent's ticket, or one delegated to someone else, is refused.

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

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

Annotations already flag destructive=true and non-idempotent, and the description adds substantial behavior beyond them: the base-SHA optimistic-concurrency refusal ('The write is refused, with what changed, if the description has moved since'), the sign_off/AskUserQuestion retry flow, and the user-approval path for descopes. This tells the agent exactly what can go wrong and how the call may return without mutating.

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

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

The core purpose and its contrast with comments are front-loaded, and most sentences carry non-obvious rules. It is dense and runs long with several parenthetical asides (source lists, Claude Code sign-off), which slightly taxes readability but each clause is doing work.

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

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

An output schema exists, so return values need not be described, and annotations carry the safety profile. Given the tool's complexity (8 params, nested patch array) the description covers the concurrency, sign-off, and descope flows that an agent would otherwise guess wrong; nothing essential is missing.

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

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

With 100% schema coverage the baseline is 3, but the description adds real meaning the schema lacks: the evidence format for ticked Done when items ('- [x] <item> · <evidence>'), what qualifies as a check versus a merge/deploy, and the semantics of reconciled_through/accounts_for ('accounts_for saying how each skipped comment was handled'). This meaningfully enriches several parameters beyond their structured definitions.

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

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

The description opens with a specific verb+resource: 'Change what the ticket says is true by patching named description sections (Observed, Cause, Fix, Done when).' It immediately distinguishes itself from the sibling comment tool ('The description is current state; comments are the log'), so an agent can tell it apart from comment/set_status without opening a schema.

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

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

It gives clear conditional guidance: pass reconciled_through to record the description reflects a thread, tick a Done when item only once its check has run, and require descope_reason/descope_risk when removing unticked items. It contrasts with comments as the alternative, though it never states when *not* to use set_state versus a plain comment.

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

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

Annotations already declare destructive=true, idempotent=true, readOnly=false, but the description adds substantial unannotated behavior: it can refuse and return a diff if the description changed since claim, it reads gates a project may hook onto the tool, and reason gets posted as a comment. Only the valid state-name domain is left unstated.

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

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

Purpose is front-loaded in the first sentence, and subsequent sentences carry real behavioral payload. However, the second sentence is a long run-on packing several conditional clauses, which slightly hurts parseability.

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

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

With an output schema present, return values need not be explained, and annotations carry the safety profile. The description covers gating, refusal, and comment side effects well; the main omission is that valid workflow state names are never enumerated or pointed to.

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

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

Schema coverage is 100%, so issue, state, and reason are already documented in the schema (including that reason is required for canceled and posted as a comment). The description largely restates that for reason and adds little new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource: 'Move a ticket to a workflow state by name.' It also distinguishes itself from the sibling set_state by clarifying that this call 'carries no evidence of its own' while set_state writes it, so an agent can tell the two apart without reading schemas.

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

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

Gives explicit conditional routing: moving to Done requires a completed 'Done when' section, merged cited PRs, and a claim, while moving to canceled skips those checks and requires a reason. It names set_state as the prerequisite tool for embedding evidence, so when-to-use is fully covered.

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

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

Annotations already cover readOnly/idempotent/non-destructive safety, so the bar is lower; the description adds meaningful context by explaining what the returned identity semantically drives (claims, self-referential fields). It does not need to explain return values since an output schema exists.

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

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

Two tight sentences, the core meaning front-loaded before the clarifying note about claims. No wasted words.

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

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

With zero params, a full output schema, and complete annotations, the description only needs to convey the identity's meaning and its relationship to related fields. It does so adequately.

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

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

The tool takes zero parameters, so the baseline is 4. There are no argument semantics to clarify beyond the empty schema.

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

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

States specifically what the tool reveals: the Linear user or app behind the token. It clearly identifies the resource and scope, though it does not explicitly name which sibling (e.g. check_claim vs claim) it differs from.

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

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

The description implies usage by tying the result to claims, assignee_is_me, and delegate_is_me, giving the agent context for interpretation. However, it never states when to call this tool versus alternatives like check_claim, so guidance remains implicit.

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