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 only declare the safety profile (destructive, non-idempotent, closed-world); the description goes further by disclosing the side effects of each kind — ask opens a row in Open questions, answer flips it to ANSWERED with a link, closed_by writes a Linear relation and records under Fix, patches mutate description sections. It does not mention the base/description_sha concurrency refusal (that lives only in the schema) or duplicate-post behavior, which keeps it from 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?

Purpose is front-loaded in the first three words, and each following clause is a compact kind:behavior pair with no filler. It reads as a dense colon-separated block rather than flowing prose, but nothing in it is redundant against the schema or annotations.

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

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

For a 10-parameter, five-mode write tool with annotations and an output schema, the description covers the mode semantics and the sibling boundary that an agent needs. It leaves the return payload to the output schema (correct) and only omits failure/duplicate behavior that the schema's base note partially covers.

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 90%, so the baseline is 3, but the description adds cross-parameter semantics the schema cannot express: which patch/kinds pair with which field (evidence → optional Observed patch, correction → mandatory description patch, answer → answers id, closed_by → closed_by + relation). That mapping is genuine added meaning over the enum listing.

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?

Opens with a concrete verb+resource ("Post a typed comment") and then enumerates the five kinds, so an agent knows this is a polymorphic write endpoint rather than a generic note-taker. It also carves out scope against set_status ("Move the state separately"). The tool name "comment" alone is vague, but the description disambiguates it well.

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?

Each kind carries its own condition of use and its prerequisite: correction "must carry the description patch", answer "must name the row it closes (answers: \"Q3\")", closed_by names the carrying ticket and sets the relation. It also states explicitly that state changes belong to set_status, which is a real exclusion. This is about as close to per-kind when-to-use guidance as a tool gets.

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 the mutating, non-idempotent, non-destructive profile, and the description adds substantial behavior beyond that: the server auto-discovers the team's closest open tickets and refuses until placed, parent-without-project is refused, and the result lists filed tickets no agent has claimed. It also ties section validation to set_state and explains the Done-when/set_status dependency.

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?

It is front-loaded with the core action, but the remaining prose is a long run-on chain of dependent clauses ('A new ticket needs a home... and ends up in a project...') that is harder to parse than necessary. Every sentence carries useful information, so it is not padding, but the structure could be tighter.

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 7-param, mutating tool with conditional server-side refusals, the description covers the branching logic, required sections, and return summary well; an output schema exists so return values need no explanation. It leaves only minor gaps such as the exact shape of the refusal response, which is acceptable.

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 86%, so baseline is 3, but the description adds real meaning on top: new_because is capped at 300 characters and posted on the ticket, distinct_from names the server-named tickets, and Done when sections must be checklist items. Only marginal gaps remain for `team`/`title`/`project_id` semantics, which the schema covers.

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?

Opens with a specific verb+resource ('Create a ticket'), and the rest of the text clearly delineates it from siblings like comment, set_status and set_state by describing filing semantics. It is unambiguous for an agent, though the purpose statement is buried under a dense block of constraints rather than front-loaded crisply.

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 when-to-use branches: widen an existing ticket, file under one with `parent`, or file apart using `new_because`/`distinct_from`. It also states the exemption (team with no open projects), the refusal conditions, and the requirement that a parent with no project is refused. This is a full decision tree, not vague 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 cover the safety profile (readOnly, idempotent, non-destructive, closed world), so the bar is lower. The description still adds genuinely new behavior: it errors when LINEAR_PRINCIPAL_TOKEN is unconfigured or resolves to someone other than LINEAR_PRINCIPAL_ID, and it notes the payload mirrors `notifications`.

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 front-loaded sentences that state what it reads, why it is separate from the sibling, and when it fails; nothing is redundant. The em-dash stacking makes it slightly denser than necessary, keeping it out of the top band.

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. What remains — identity/principal semantics and the token-resolution error conditions — is exactly the context an agent needs before invoking, and it is all present.

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

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

Schema description coverage is 100% (all four params documented, including defaults and formats), so the schema does the heavy lifting. The description adds only the hint that the shape matches `notifications`; it gives no additional parameter semantics. 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 resource (the principal's inbox) and immediately distinguishes it from the sibling `notifications`, which reads this identity's own inbox. The sentence 'Same shape, deliberately a separate tool rather than a parameter' makes the boundary with the sibling unambiguous without opening either 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?

The description names the alternative (`notifications`) and the condition that selects it ('a different person's notifications'), plus the failure conditions under which this tool must not be used. It stops short of an explicit trigger phrase such as 'use when acting on behalf of the human', leaving a small amount of 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 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?

Goes well beyond annotations: per-id refusal of notifications not returned by the sibling read tool, the required principal token with write access, and the read-only-token failure mode with the message to relay to the user. Annotations cover the safety profile (idempotent, non-destructive), and the description adds prerequisite and partial-failure semantics.

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 the disambiguation before anything else, and every sentence carries new information. Slightly dense as a single paragraph with several parentheticals, but nothing is wasted.

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 return shape need not be described, and the description still covers scope, selection modes, prerequisite auth, and partial-refusal behavior. Nothing an agent needs to call this correctly 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 coverage is 100%, so the baseline is 3; the description adds meaning by framing only_agent_actors as 'fleet bookkeeping' and clarifying the interaction between before and only_agent_actors (only unread agent-caused notifications created before a date).

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 (mark read) and resource (notifications in the principal's inbox), and explicitly positions itself as the write twin of get_principal_notifications and as distinct from the similarly named mark_notifications_read. An agent can disambiguate among siblings 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?

Names the two selection modes explicitly (pass ids, or only_agent_actors: true for agent/integration-caused unread notifications) and the alternative tools it must not be confused with. It also states the constraint that only notifications previously returned by get_principal_notifications are markable.

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?

With annotations only declaring destructive=true, non-idempotent, and not read-only, the description adds critical behavioral context: names are resolved to IDs first, the entire call is refused if any name is unknown or ambiguous, and nothing is half-applied. It also discloses permission rules around reassignment, take_over, and delegations, which an agent could not infer from annotations alone.

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 four dense sentences, all of which earn their place: purpose, alternatives, atomic validation behavior, and permission rules for assignment changes. It is front-loaded with the primary action and does not repeat annotation or schema content.

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

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

Given 18 parameters, destructive annotations, an output schema, and 83% schema description coverage, the description supplies the missing high-level context: alternatives, atomic refusal behavior, and reassignment/delegation constraints. It does not need to explain return values because an output schema exists, and it covers the complexity inherent in this mutation 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 description coverage is 83%, so most parameters are already documented in the schema. The description lists the mutable field categories but does not add format, syntax, or edge-case meaning beyond what the schema provides for individual parameters. Baseline 3 is appropriate when structured fields carry the parameter semantics.

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 and resource: 'Change a ticket's fields other than its content.' It then enumerates the field categories and explicitly distinguishes the tool from set_state and set_status, which handle description and workflow state respectively. An agent can identify this as a field-mutation 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?

The description names explicit alternatives and constraints: description changes go through set_state, workflow state through set_status, taking over an assignment needs take_over, and other agents' tickets are refused. It gives clear when-not conditions and routing guidance for an agent's own identity and for the human principal case.

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?

Goes well beyond the annotations by disclosing refusal behavior ('refuses, returning the diff, if the description changed since you claimed it'), the empty-evidence contract ('this call carries no evidence of its own'), external gate checks a project can hook, and the side effect that canceled reasons are posted as a comment. This is unusually rich behavioral disclosure layered on top of destructiveHint/idempotentHint.

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 purpose is front-loaded in the first clause, but the remainder is a single tangled run-on sentence ('...and your claim, and refuses, returning the diff, if the description changed since you claimed it') that is grammatically broken and hard to parse. The content mostly earns its place, but the structure does not.

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 explained, and the description still covers refusal/diff behavior. For a tool with conditional gates and mutation semantics, it conveys enough that an agent can call it correctly in both the completed and canceled paths, though the set_state cross-reference stays muddy.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds genuine semantic meaning about the 'state' parameter: completed names trigger Done-when gates and canceled names bypass checks and consume 'reason'. It does not add anything about 'issue' 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?

Opens with a specific verb+resource+scope: 'Move a ticket to a workflow state by name.' That is unambiguous about what the tool does. However, it does not differentiate itself from the confusingly similar sibling set_state, which it references as a separate tool for writing evidence, leaving the agent to disambiguate the two names on its own.

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 guidance: completed states require the Done-when checklist, merged PRs, and a claim, while canceled states skip those checks and need a reason. This is real when-to-use context. It stops short of stating when to prefer this over set_state or set_fields for state changes.

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.