BoardMark

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

Annotations already declare non-read-only, non-destructive, non-idempotent, but the description adds the side effect that matters ('its writer is told') and a full 409 version_conflict protocol with details.current / details.current_version, re-read-and-retry, and 'never overwrite blindly; ask the user'. It stops short of saying what happens if you acknowledge twice, which matters given idempotentHint=false.

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 first two sentences are front-loaded and tight, and the open/close distinction is placed immediately after the action. The trailing WRITE paragraph is largely shared boilerplate that enumerates unrelated reads (list_comments, list_sprints, get_issue) not relevant to acknowledging a doc handoff, which is modest noise.

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?

No output schema exists, so the description carries the burden, and it covers preconditions, the version source, the notification side effect, and conflict recovery. Two gaps remain: nothing about repeated acknowledgments despite idempotentHint=false, and no explanation of whether `reason` is meaningful here.

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 75%, so the schema already documents project_key, version, and reason. The description adds real value for `version` by telling the agent where to obtain it (get_doc, get_issue, read_file) and that it is the latest read, but says nothing about `slug` (H- pattern) or when `reason` is worth sending, leaving it close to baseline.

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

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

States a specific verb and resource ('Say you have read a handoff') plus the resulting state change ('an open handoff becomes acknowledged; the writer is told'). It explicitly distinguishes the adjacent operation by noting it does not close the handoff and that update_doc `status: closed` does, so an agent can separate it from update_doc 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?

Gives concrete discovery paths that identify the precondition (list_docs `for_me: true`, or get_project `docs.open_handoffs_for_me` > 0), the required input source (the `version` from get_doc), and an exclusion ('Do this only after you have actually read it'). It also names the sibling that performs the different action (closing) instead of this one.

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

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

Discloses side effects that annotations cannot express: the answered author gets an email, mentioning a person emails them but only if they can open the project, and commenting makes the token's user a watcher. It also names the exact failure mode ('A seq that does not exist on this issue → 400 validation_failed (field reply_to)') and clarifies that replying to a reply re-files under the thread root.

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?

Long but front-loaded and dense — every sentence after the opening carries operational detail (colour semantics, image embedding, mention ids, threading). Slight deduction: the first sentence duplicates the title verbatim and the upload chain is stated twice.

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?

A mutation tool with no output schema; the description covers side effects, error mode and threading adequately. It never states what the call returns (e.g. the new comment's `seq`, which the agent needs for later reply_to targets), which is the main remaining gap.

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

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

Schema coverage is 67%, and the description compensates for the uncovered/underspecified parts: markdown/colour conventions with allowed values and semantics, inline image syntax including the angle-bracket escape for paths with spaces, the mention URI format sourced from list_people, and the reply_to threading rules. The `reason` parameter is documented only in the schema, keeping it from a 5.

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 ('Add a comment') and immediately scopes it against its siblings: reply vs. new top-level comment, attachment flow via request_upload → PUT → attach_file, and mentions. An agent can distinguish this from update_comment, delete_comment and list_comments 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?

Gives explicit routing rules: 'To REPLY to a comment, pass its seq... omit it (or null) for a new top-level comment', plus the prerequisite chain request_upload → PUT → attach_file. It does not explicitly say when to use update_comment instead of posting a new one, so it stops short of a full 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?

Adds substantial behavior beyond the annotations: local x-mcp handling, no board-core route/404, per-key move_to_release checks, one 409 retry with fresh read, skipped semantics, permission requirements with 403 per issue, and release preconditions with whole-call 404/409 behavior. This is consistent with readOnlyHint=false and destructiveHint=false.

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 and the description is organized into mechanics, permissions, workflow, and results. However, it repeats the opening sentence nearly verbatim later and restates the one-by-one move behavior, so not 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?

For a complex bulk mutation with no output schema, the description covers preconditions, permissions, failure modes, result fields, and retry guidance. An agent has enough context to invoke it correctly and interpret results.

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 75%, so the schema already documents most parameters. The description adds useful meaning for reason (kept in scope history and run-log), issue_keys (up to 50, epics children follow), and release_id (must exist and be planned), though it adds less for project_key.

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, and scope: put up to 50 issues/epics into one planned release in one call, with per-issue results. It also distinguishes itself from move_to_release by emphasizing the bulk one-call behavior, so an agent can identify it as the batch wrapper.

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

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

Provides an explicit workflow: find issues first with search_issues using filters such as release=none and status ids, then call this tool with the keys and one reason. It gives concrete examples, says to retry only failed keys, and tells callers to chunk when there are more than 50 issues.

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 readOnlyHint=false and destructiveHint=false, so the write safety profile is covered; the description adds real value beyond that with the optimistic-lock protocol and the 409 conflict recovery procedure. It does not address whether a new assignment notifies the assignee, which is the main behavioral unknown left.

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-loaded with the action and the null-unassign rule, then the write/version protocol as a clearly separated block. Efficient, with no filler sentences; the only small cost is the redundant restatement of the title line.

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 a fully documented 5-param schema, annotations present, and no output schema to explain, the description covers everything an agent needs to invoke correctly: the unassign sentinel, version sourcing, and conflict handling. Missing notification semantics is a minor nicety, not a blocker.

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 does add meaning beyond the schema for `version` (which tools to read it from, what to do on conflict), but its statement that assignee is 'a user id (`usr_…`) or null' omits the `agt_…` agent-account form the schema explicitly allows — slightly narrowing rather than enriching the parameter definition.

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 ('Assign or unassign') and pins the unassign case to assignee=null. It does not, however, distinguish itself from the sibling update_issue, which can plausibly also change an assignee — an agent must infer the difference.

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 operational guidance: pass null to unassign, source `version` from a prior read (naming the specific read tools), and on 409 re-read/re-apply rather than overwrite, escalating to the user when changes conflict. It lacks a when-to-use-this-vs-update_issue statement.

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 write-ish profile (readOnlyHint=false, idempotentHint=false, destructiveHint=false). The description adds the sequencing precondition and what the return value is for, but says nothing about retry behavior despite idempotentHint=false, nor what happens to the upload if this confirm step is never called.

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-loaded with the core action, then the sequencing, then the output usage rules. The opening sentence is a verbatim repeat of the title, which is minor waste; the markdown escaping rule is dense but genuinely necessary because screenshot filenames break naive markdown links.

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?

No output schema exists, and the description does the required work by stating that it returns the attachment `path` and exactly how to embed that path. It leaves failure modes (expired upload_id, failed confirm) undiscussed, but an agent has enough to call it correctly.

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

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

Schema coverage is 50%: `reason` is richly documented in the schema, but `upload_id` has no description anywhere. The 'after the PUT succeeded' framing indirectly tells the agent where upload_id originates, but the description never mentions the parameter or its format.

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 (confirm an upload, produce an attachment path) and immediately locates it in the workflow as 'Step 3 of 3: after the PUT succeeded'. This clearly distinguishes it from request_upload (which starts the flow) and from list_attachments/get_download_url.

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 precondition ('after the PUT succeeded') and explicit downstream usage: put the path in add_comment `attachments` or an issue body. It does not name a when-not case or an alternative sibling (e.g. get_download_url for reading an existing attachment), so it stops short of the top band.

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 idempotent=false, and the description adds the substance behind that: exactly what is destroyed (one sprint's active state), where open issues go under each `move_open_issues_to` mode, why an active target sprint is refused, and the 409 version_conflict recovery procedure (re-read, re-apply, retry, never overwrite blindly). That is a materially richer behavioral picture than the 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?

Front-loaded with the action and its scope, then permissions, then fallout, then write/conflict protocol — a sensible ordering. It is dense but nearly every clause carries a constraint (D141, D62, 400 case, 409 case); the only waste is restating the title's 'other active sprints are unaffected' twice.

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

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

For a destructive, non-idempotent 5-parameter mutation with no output schema, the description covers authorization, side effects on issues, target-sprint eligibility, default behavior, and concurrency-failure handling. An agent could invoke this correctly on the first attempt.

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 real semantics the schema does not: `version` must come from the latest read and stale values produce a 409 with details.current, and `move_open_issues_to` refuses an active sprint while `new_sprint` creates a planned sprint right after this one. Only `reason` is left entirely to 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?

States a specific verb and resource ('Close one active sprint') and immediately bounds the scope: 'Closes ONLY the sprint in `sprint_id` (it must be active); other active sprints and their issues are untouched.' This distinguishes it from `update_sprint` (edits) and `move_to_sprint` (issue relocation) 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?

Gives explicit preconditions (project_admin, or a member when `sprint_control` is `members`; agent tokens per that role) and explicit routing guidance for the tricky case: handing work to another running sprint is refused with 400, so close into backlog then use move_to_sprint. When-to-use, when-not, and the alternative are all named.

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: resulting status, the generated system message text, the audit event name, the 30-day reversibility window, permission scope ('any member'), notification/email delivery, a text-only limitation, and the 'via AI agent' attribution. The only blemish is the claim that closing a closed case 'changes nothing (200)', which reads as idempotent behavior while idempotentHint is declared false — a minor tension rather than a safety-relevant conflict.

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 action and its state effect before the routing guidance, which is the right order. It loses a point for duplication — the opening line restates the title verbatim and the 30-day reopen window is stated twice in adjacent paragraphs.

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 no output schema, the description still covers outcomes (status → closed, 200 no-op on repeat), permissions, notification behavior, and content constraints. An agent has everything needed to decide, call, and predict the result.

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% (case_id with its ULID pattern is fully documented inline), so the schema already carries the parameter semantics. The description adds nothing about the id argument beyond what the schema states, which is the expected baseline for a single fully-described parameter.

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

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

States a specific verb+resource (close a support case) and scopes it ('of your company, any member'). It also distinguishes the operation from its neighbors by name (reopen_support_case, get_support_case) and from the issue family (create_issue, search_issues), so an agent can route correctly 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?

Gives an explicit trigger ('Only when the user says the problem is solved or no longer needed') and an explicit exclusion ('never for the user's own project work — that is issues'). The support-case vs. issue boundary is exactly the ambiguity an agent would otherwise get wrong.

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

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

Annotations already mark this as a non-read-only, non-idempotent creation tool, but the description adds substantial behavioral context: 403 permission paths, 409 duplicate-slug handling, 413 size limit, server-numbered handoffs, history message behavior, label scoping, and HTML rendering rules. This is far beyond what the annotations 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?

The content is front-loaded and structured around kind distinctions, but the opening sentence duplicates the title and several permissions/error details are repeated in the following paragraph. For a 10-parameter tool some length is justified, but the description is denser and more repetitive than necessary.

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 this is a create mutation with no output schema, the description is complete enough to call correctly: permissions, error codes, slug behavior, handoff addressing, notes labels, size limits, and the meaning of note/brief content for AI agents are all covered.

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 80%, but the description adds meaningful semantics for kind, slug defaults and conflicts, handoff numbering, 'to' team ids and omission behavior, related issue keys, and notes-only labels. It also clarifies markdown/body limits and rendering behavior, leaving little ambiguity for the caller.

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

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

The description states a specific verb and resource ('Create a project doc') and distinguishes all four doc kinds by purpose and audience. It clearly separates member-created notes/handoffs from admin-only briefs and the web-app-only company_brief, so an agent can tell exactly what this tool creates versus get_doc/update_doc.

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 explicit when-to-use rules for each kind, permission constraints (members vs project admins vs viewers), and the recommended alternative when a slug already exists ('get_doc it and update it instead'). It also names the case not handled here (company_brief) and routes it to the web app.

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 defaults for status, priority and sla_due, which fields are computed and reject writes (400 formula_readonly), the specific 400/403 error codes and their meanings, the cross-project link restriction (403 link_target_forbidden), and that the key is server-assigned. This is the kind of behavior an agent cannot get from the schema or 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 core facts are front-loaded, but the body is a single dense paragraph of several hundred words stitched together with internal spec references (D129, D130, D131, D137, D143, D179) that the agent cannot resolve. Domain playbooks for sales, service desk, budget, roadmap and feedback could be structured or trimmed rather than run together.

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 17-parameter mutation tool with no output schema, it covers defaults, error modes and the major domain shapes well. But it never says what the call returns (whether the created issue/key comes back), leaves several parameters unexplained, and the phantom `links` parameter creates a mismatch with the schema the agent will actually see.

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 only 59% schema coverage, the description does add real semantics for `fields` (id keys from get_project, per-type value mapping, required/unknown/formula failure modes), `priority`, `status` and `sprint`. However it silently omits meaning for labels, points, parent, assignee, release, severity and reason, and it discusses a `links` parameter that does not exist in the schema (additionalProperties is false) — a misleading detail that offsets some of the added value.

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

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

The first sentence states a clear verb and resource ('Create an issue') and adds the non-obvious fact that the key is server-assigned, which an agent needs so it doesn't try to supply one. It does not explicitly distinguish itself from update_issue or name a sibling, so it stops short of a 5.

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

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

Gives concrete when-to guidance: set priority only when the user or issue makes it clear, omit sprint for the backlog, ask which sprint when parallel sprints are active, ask who the requester is when unclear, and leave status out for installments. That is real decision guidance, though there is no explicit statement of when not to use this tool versus alternatives such as update_issue.

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

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

Beyond annotations, the description discloses the initial status (planned), default gate behavior, agent-token restrictions, 403 error codes, and that created_by_agent is recorded. It also explains that gate edits, baseline locking, shipping, reopening, and deletion remain people-only operations.

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 content is front-loaded and useful, but the description repeats the same agent restriction and default-gate information across multiple paragraphs. It is verbose and could be shortened without losing behavioral guidance.

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

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

For an 8-parameter creation tool with no output schema, the description covers prerequisites, agent-specific constraints, default behavior, error conditions, and the next step. An agent has enough context to avoid forbidden calls and to know when creation is allowed.

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 63%, and the description adds meaningful semantics for key parameters: name uniqueness, target_date as the planned production day, reason for agent logs, and the agent prohibition on gate/copy_gate_from. Some schema-documented parameters still rely on the schema, so it is strong but not fully compensating.

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

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

The description states a specific verb and resource — create a planned release — and clearly scopes it to the project, including the default gate and agent restrictions. It distinguishes this from related actions such as adding work with add_to_release and from people-only actions like shipping or locking the baseline.

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 explicit when-to-use guidance: only when the user asks for a release, with required fields and prerequisites. It also names the follow-up tool add_to_release and explicitly says agents must not send gate or copy_gate_from, routing that decision to people in the web app.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=false and idempotentHint=false, so the description is not carrying the safety profile. What it does add is genuinely useful: the exact permission model and the get_project dependency. It does not mention what happens on a duplicate sprint name, whether the sprint starts immediately, or what is returned — gaps that matter for a non-idempotent mutation.

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 first sentence repeats the title verbatim, including the D141 reference, and the second sentence restates the same permission rule in slightly more detail. Roughly half the text is duplication rather than new information.

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

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

For a mutation tool with no output schema and six parameters, the definition covers the authorization story well and points to get_project for the deciding condition. It omits what the call creates/returns (sprint id?), duplicate handling, and any constraint linking start and end, which an agent needs to invoke it safely.

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 67%; project_key, start, end and reason carry descriptions, while name and goal have only constraints. The description says nothing about any parameter — no field semantics, no date-range or ordering rule (e.g. whether end must be after start), no note that goal is optional. It adds zero meaning beyond the schema.

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

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

The first sentence names a specific verb and resource ("Create a sprint") and adds an authorization scope, which is enough to separate it from siblings such as close_sprint, update_sprint, list_sprints and move_to_sprint. It never explicitly contrasts with those siblings, but the resource 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?

"Requires project_admin, or any member (not a viewer) when the project's `sprint_control` is `members` (see get_project); otherwise forbidden" tells the agent when it is allowed to call, and points at get_project to resolve the condition. It gives no guidance on when to create a new sprint versus reusing one from list_sprints, nor any prerequisite ordering.

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

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

Annotations already mark the tool as destructive, idempotent, and not read-only, but the description adds substantial context: no trash/restore, read-only/suspended company behavior, link rendering as "file deleted", emitted event, and audit event. It does not contradict the annotations.

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

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

The core behavior and permissions are front-loaded, and most details earn their place for a destructive operation. However, the title wording and the agent-deletion restriction are repeated, which keeps it from being maximally concise.

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

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

For a destructive tool with no output schema and complex permission rules, the description covers permanence, permissions, error responses, event publication, audit behavior, and the required ID source. An agent has enough context to invoke it correctly.

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

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

Schema coverage is 50%: the reason parameter is fully documented in the schema, but attachment_id has no schema description. The description compensates by saying to get attachment_id from list_attachments, though it does not discuss reason or add further parameter constraints.

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: permanently deleting an attached file, with no trash and no restore. It also distinguishes the retrieval path by naming list_attachments as the way to obtain the attachment_id.

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 defines who may delete, when an agent may delete, when admin power does not apply, and that the user should be asked before deleting. It also names list_attachments as the source of the required ID and gives clear failure conditions.

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 past the annotations (destructiveHint/idempotentHint) by spelling out exactly what the destructive operation does: body emptied, deleted: true, seq/replies/links preserved, old text retained in history, and it returns the tombstone. It also documents the concurrency protocol (version from latest read, 409 version_conflict with details.current, re-read and re-apply, never overwrite blindly), which is the behavior an agent most needs before writing.

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 content is right but it is stated two and three times: 'leaves a tombstone' appears in the title line, again in paragraph two ('The file stays with an empty body and deleted: true'), and again in paragraph three ('Leaves a tombstone: the body is emptied...'), and the author/project_admin rule is duplicated verbatim. Roughly half the text could be removed with zero information loss, which is the opposite of front-loaded economy.

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

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

For a destructive mutation with no output schema, this covers everything an agent needs to call it safely: mandatory version sourcing, permission matrix, both error codes and their recovery, and the exact post-state of the resource. Nothing material 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% and every parameter already carries a description, so the baseline is 3. The description does add real value on `version` (where to source it, how to recover from a version_conflict) and `seq` (get it from list_comments), but it says nothing about the optional `reason` parameter, so the add is partial rather than a full supplement.

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 first line states a specific verb and resource (delete a comment) plus its two defining traits: version is mandatory and the delete is a soft delete ('leaves a tombstone'). This clearly separates it from update_comment and the other delete_* siblings without needing to open 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?

It gives an explicit gating condition ('Only when the user asked'), permission rules (author or project_admin; imported unmatched Jira comments need project_admin), and the exact failure modes 403 not_author and 409 comment_deleted. What's missing is a named alternative — it never says 'to change text use update_comment' — so the agent must infer the escape hatch rather than being routed to it.

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/idempotent, but the description adds substantial context beyond them: deletions are recoverable from history, permission tier differs by kind with the exact error code (403 doc_admin_only), and a full conflict-recovery protocol for 409 version_conflict including re-read/re-apply and escalating to the user. This is exactly the operational detail 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?

Front-loaded and scannable, but several points are stated twice: the history/restore recoverability appears in the opening line and again mid-paragraph, and the brief-admin/403 note is repeated verbatim at the end. Tightening would remove roughly a third of the text without losing information.

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

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

For a destructive write tool with no output schema, the description covers the three things an agent needs: who may delete what, how to get a valid version, and how to recover from a version conflict or undo a mistaken delete. Nothing material 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 earns more by specifying provenance for `version` ('from your latest read' with concrete sibling tools) and what to do when it goes stale. It does not add much for `reason` or `slug`, which the schema already documents.

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 (delete a doc), scopes permissions per doc kind, and explicitly names the recovery counterpart (restore_doc_version). An agent can distinguish it from update_doc, get_doc_history, and restore_doc_version 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?

Gives an explicit gate ('Only delete when the user asked for it') and an explicit anti-pattern with the alternative to use instead ('Never delete a doc to "fix" a bad edit — use get_doc_history + restore_doc_version'). It also names the prerequisite read (get_doc) for obtaining `version`.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, but the description adds what the annotations cannot: deletion is irreversible from MCP, the cascade removes subtasks (with the Sales & Billing / installments example), and 409 version_conflict must be resolved by re-reading rather than overwriting. That is concrete, actionable behavioral context beyond structured fields.

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

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

Front-loaded with the destructive purpose, then irreversibility, then the version/WRITE protocol — a sensible order. It loses a little to redundancy: the cascade behavior is stated twice (title plus body) and the WRITE block is dense, but nothing is padding for padding's sake.

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

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

For a destructive, version-guarded mutation with no output schema, the description covers every decision an agent must make: whether to call it, what else gets destroyed, how to obtain the version, and how to recover from a conflict. No material gap remains.

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

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

Schema coverage is 100%, so the schema already documents all four parameters and the baseline would be 3. The description earns above baseline by explaining that version comes from 'your latest read' and enumerating acceptable sources (get_issue, list_comments, list_sprints, get_doc, read_file), which is meaningful operational guidance the schema does not give.

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 ('Delete an issue') and distinguishes it from siblings such as delete_comment, delete_doc and delete_attachment by naming the issue object explicitly. The cascade scope ('its subtasks are deleted with it') further pins down what this tool does that no sibling does.

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 an explicit gate — 'Only delete when the user asked for it' — and an instruction to warn before deleting a parent, plus the prerequisite that version must come from a prior read. It never names a non-destructive alternative (e.g. transition_issue to close instead of delete), so the when-not guidance is cautionary rather than comparative.

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 read-only, idempotent, non-destructive, closed-world behavior. The description adds meaningful behavioral context beyond annotations: the tool may return `not_implemented` until old object versions are retained, and the agent should tell the user. It still omits return/pagination details, but for a diff tool the failure caveat is substantial.

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

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

Two sentences, front-loaded with the operation and immediately followed by the operational caveat. No filler or repetition beyond the title phrase.

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 read-only diff tool with annotations covering safety, the description supplies the core purpose and a critical backend limitation. Since there is no output schema, it could say more about the returned diff format or reachable paths, but the detailed path schema already carries permission and layout constraints.

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

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

Schema coverage is 50%; `path` and `project_key` are documented in the schema, but `from` and `to` rely mostly on their regex patterns. The description adds that the operation compares two commits and that `to` defaults to current, but it does not explain the commit-hash semantics or required/optional distinction beyond that.

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 operation—producing a unified diff—for a single path between two commits, and notes that `to` defaults to current. This is clear enough to distinguish from read/list/history siblings, though it does not name `get_history` or any alternative 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 description implies use when comparing a path across commits and gives an important fallback instruction if the backend returns `not_implemented`. It does not say when to choose this over `get_history`, `read_file`, or other siblings, nor does it list prerequisites or exclusions.

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

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

Adds substantial context beyond the annotations: replies arrive in the case thread and are also emailed to followers, every company member can see/answer every case, files cannot be attached here (web app only), and writes are labeled "via AI agent". It does not explicitly state that following persists as a subscription until unfollow_support_case, which is the one behavioral detail an agent must infer from the verb plus readOnlyHint=false.

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-loaded with purpose, then usage, then behavior; each sentence carries information an agent needs. Slightly verbose with some overlap between the title/opening line and the body (the idempotency tag is repeated), 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?

For a one-parameter tool with a rich annotation set, the description covers purpose, routing away from issue tools, notification behavior, permissions, and limitations. No output schema exists, and the description still conveys what the caller/user receives.

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 case_id parameter is fully documented in the schema (pattern, ULID format, spec reference). The description adds no parameter-level meaning, so the baseline of 3 applies.

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

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

States a specific verb (follow) plus resource (support case) and the concrete effect (the user receives the case's emails and bell items). It explicitly separates support cases from issue tools (create_issue, search_issues) and is clearly distinct from siblings like get_support_case and unfollow_support_case.

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 an explicit when-to-use (user wants help from the BoardMark team or reports a bug, sign-in, billing, or feature request), an explicit when-not (never for the user's own project work — that is issues), and a behavioral gate ("Only when the user asks"). Nothing is left to inference.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), so the description's added value is the scrum-only precondition and the possibility of a not_implemented result while the daily snapshot is being built. That is a genuinely useful failure-mode disclosure an agent could not infer from the schema. Return payload shape is not described, but no output schema exists to offset it.

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 the purpose before the constraints. No filler; the only mild redundancy is restating 'scrum only' twice (title and body).

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 two-parameter read with full schema coverage and no output schema, the description covers scope, iteration pattern, and the not_implemented case. What the returned series actually contains (dates, points units, date range) is left implicit, which is the remaining gap.

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

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

Schema coverage is 100% and both parameters carry patterns and examples, so the description's only addition is the 'one sprint per call' constraint on sprint_id. That is a marginal semantic gain over structured fields, making the baseline 3 correct.

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 first sentence names the specific resource and metric (daily remaining points) and constrains it to a sprint, in scrum mode only. That separates it from siblings like get_summary, get_project_insights, or list_sprints, though it does not explicitly name those alternatives.

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 a clear calling pattern: one sprint per call, repeat per active sprint when several exist. It also sets expectations for the not_implemented response and instructs the agent to surface that to the user. It stops short of pointing to list_sprints for discovering sprint ids, which would complete the routing story.

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 cover read-only/idempotent safety; the description adds the gated behavior an agent actually needs: Premium required with 403 `plan_required` + `details.feature`, company-admin-only with 403 `forbidden`, JWT/company mismatch -> 404, bad range -> 400 `invalid_range`. It also discloses the metric definition (first in-progress -> done, median/p85) and the partial-data `cycle_measured` of `cycle_total` caveat with an explicit no-extrapolation instruction.

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-loaded with scope, then auth, then semantics, then output interpretation – a sensible order with no filler sentences. Minor redundancy: the title is restated verbatim and the "measured `cycle_measured` of `cycle_total`" phrasing appears twice in slightly different forms.

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 no output schema, the description still tells the agent what comes back (`projects`, `people`, `agents`, `people[].done_cards`/`done_points`, `unassigned`, cycle median/p85) and what their absence means. Combined with the auth and error contract, an agent has everything needed to call and report on it correctly.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds decision-level semantics: the range defaults to the last 30 days and should only be overridden when the user specifies one, and `compare` adds the previous period. That is usage meaning the schema's type/default text does not convey.

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 and scope ("Flow numbers across every project of the company, with people and agents") and explicitly relates it to the sibling: "Same numbers as `get_project_insights` pooled over every live project, plus `projects`, `people` and `agents`." An agent can distinguish it from get_project_insights 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?

Gives concrete when-to-use rules: company-wide rollup vs. the per-project sibling, pass `from`/`to`/`compare` only when the user names a range, and CSV exports are web only. It also names the failure modes that change the answer (non-admin -> absent people/agents -> say so, never invent).

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, so the description rightly focuses on what they cannot say: the exact returned payload (frontmatter, body, version, last_edited), the `rules: true` flag on admin-only briefs, and the version-pinning contract that makes the subsequent write safe. It does not discuss failure modes (missing slug, access to company brief).

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-loaded and short overall, but the opening sentence duplicates the title word-for-word and the '(any kind, the company brief included)' / 'works for every kind' scope claim appears three times. Roughly a third of the text is repetition rather than new 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 no output schema, the description properly enumerates the returned fields and their meaning, and the pre-mutation version-passing workflow is explained. What remains unaddressed is error/permission behavior for the admin-only brief, which matters for a tool that reads restricted content.

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

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

Schema description coverage is 100% with rich per-field descriptions (enum meanings, slug regex, project key format), so the schema does the heavy lifting. The description adds only that `at` takes a commit from get_doc_history — which the schema already states — leaving baseline 3 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 and resource ('Read one doc') with an explicit scope qualifier — any kind, company brief included — and implicitly contrasts with get_doc_history (older versions) and the mutation tools it must precede. An agent can tell it is the single-document read rather than a listing or context bundle.

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?

'Call this before update_doc, delete_doc, restore_doc_version or acknowledge_handoff and pass the `version` it returns' is concrete prescriptive guidance, and the `at` note routes historical reads to get_doc_history. Missing only a negative exclusion (e.g. use list_docs to enumerate, get_docs_context for bulk context).

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-obvious behavior beyond that: newest-first ordering, `version` is null for a delete, and `agent_token_id` is populated only when an AI agent made the save. It omits pagination/limit behavior, which is the main remaining gap.

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-loaded with the core purpose and well under a paragraph. However, the first sentence merely repeats the title verbatim and the second sentence restates 'Every saved version, newest first' again, so roughly a third of the text is duplication rather than new 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?

There is no output schema, so the description correctly carries the return-value burden by enumerating every field and its edge case (null version on delete). Annotations handle safety. The only missing piece an agent would want is what `limit` does and whether results are truncated.

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 75% and the three required parameters (project_key, kind with enum, slug with pattern) are fully self-documented in the schema. The one undocumented parameter is `limit` (default 50, max 200), and the description never mentions paging or how many versions come back, so it fails to compensate for the coverage gap. 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 the resource precisely (every saved version of a doc) and the exact ordering and payload (commit, version, actor_user_id, agent_token_id, message, created_at, deleted). This is clearly distinguishable from get_doc (current content) and get_history (issue history), which an agent could otherwise confuse it with.

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 an older version with get_doc `at` = its `commit`, restore with restore_doc_version. That names the alternatives and the conditions that select them. It stops short of saying when this tool is the wrong choice (e.g., you only want the current doc), so it's strong but not exhaustive.

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, and the description adds substantial behavior beyond them: a 2 MB cap surfaced as `truncated: true`, BEGIN/END markers carrying a per-bundle random token so marker-lookalikes inside content can be told apart, an explicit trust model distinguishing admin rules from team-member data, and the warning that it carries no versions so a get_doc read is required before mutation.

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-loaded with the headline and the 'fastest way' framing, which is good. But the opening sentence repeats the title verbatim, and the middle is a chain of dense run-ons (template list, flags, D-spec citations) that could be tightened into a short bulleted structure without losing 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?

There is no output schema, so the description must describe the return value — and it does: overall shape, ordering, per-doc markers, the linked-projects line, the status table with WIP limits, template fields and computed flags, and the truncation signal. Given a single-parameter read tool, nothing an agent needs to interpret the result 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?

Only one parameter, project_key, and the schema already fully documents its pattern and format at 100% coverage. The description does not add meaning about the parameter itself, so the high-coverage baseline of 3 applies.

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

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

States a specific resource and form — 'A project's context as one markdown text' — and then enumerates exactly what is bundled: company/project briefs, working notes, open handoffs, status meanings, template fields, default role rules. That enumeration distinguishes it from siblings like get_doc (single doc) and get_project (metadata), so an agent can choose it without opening another 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 frames it as 'The fastest way to get a project's context' and 'Useful before working on a project you do not know,' and routes the agent onward for the adjacent cases: read missing docs with get_doc, call get_doc before changing a doc, take field ids from here for create_issue/update_issue/search_issues. When-to-use, when-to-use-something-else, and downstream use are all 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 declare readOnly/idempotent/non-destructive, so the burden is lower, but the description still adds real context: the ~5 minute expiry window, charset=utf-8 serving for text-like types, and the Content-Disposition effect of disposition=attachment. It does not say what the response body looks like (bare URL vs object), which is the main remaining gap for a tool with no output schema.

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

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

Front-loaded and reasonably short, but the first sentence merely restates the title verbatim, and the third sentence re-repeats 'Short-lived presigned GET URL' before adding the 5-minute figure. The S144/D146 reference codes are noise for an agent. Two of four sentences carry redundant framing.

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 2-parameter read tool with no output schema, the description covers the prerequisite, lifetime, and download-mode behavior adequately. The one thing an agent might still want — the exact shape of the returned value — is not stated, but the nature of a presigned URL makes that largely inferable.

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 only 50% — attachment_id has no schema description — but the description compensates by explaining it must come from list_attachments/attach_file and that it is a UUID-backed attachment reference. disposition is already documented in the schema and the description reinforces download-vs-open semantics with the original-filename detail.

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 (get) and a specific resource (short-lived presigned GET URL for an attachment), and the parenthetical scopes it to md-renderer image use. An agent can distinguish it from list_attachments or read_file 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 tells the agent where the attachment_id comes from (list_attachments or attach_file) and how to handle the short lifetime (fetch immediately, ask again after expiry). It stops short of naming when a different tool would be preferable (e.g. read_file for text content), so it is clear context rather than full alternative routing.

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 (read-only, idempotent, non-destructive), and the description adds ordering ('newest first') and the per-commit payload shape, including agent provenance fields set when an AI agent made the change. That is useful context an agent cannot get from the 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?

Two short sentences, front-loaded with the purpose and then the ordering/payload detail. Only the '(D112)' spec reference is dispensable, which is a minor waste.

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 four-parameter read tool with no output schema, the description covers the return shape and ordering well. Pagination mechanics are left to the schema's cursor field, which is acceptable, but the default page size and what an empty result looks like are not addressed.

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 75% and the path parameter already carries a long, detailed description in the schema, so the description's 'optionally for one path' adds little. The limit and cursor parameters are not discussed at all in the description.

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

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

The description states a specific verb and resource ('Commit log of the project'), and the optional path scope makes the tool's shape immediately clear. It does not explicitly differentiate from get_doc_history or diff, so it stops short of 5.

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

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

There is no statement of when to use this versus alternatives. 'Optionally for one path' implies filtering, but a reader must infer the split between get_history, get_doc_history, and diff entirely on their own.

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, and the description goes well beyond them: it discloses staleness semantics ('a person's `working` older than a day may be stale'), a 10-minute liveness window for `agent_live`, and that `readable: false` means the target cannot be opened so 'never guess the rest'. Those are agent-affecting behaviors nothing in the structured fields conveys.

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 critical instruction is front-loaded in the first two sentences, which is right. But the remainder is a single dense wall of text loaded with internal spec codes (D129, D131, D179) and deep payload detail that is disproportionate for a two-parameter read.

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 no output schema, the description carries the full burden of explaining the return value and does so thoroughly: version, user-id fields, frontmatter fields/flags/computed/children, link resolution, and rollups. It omits error behavior (e.g., missing issue or unknown project key) and any permission notes, which keeps it short of a 5.

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 both parameters are documented in-schema with patterns and examples, so the baseline applies. The description adds no additional meaning about project_key/issue_key (its only key-related content is nested keys like `KEY/R-n` inside the returned links), so it neither enhances nor compensates.

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 ('Get an issue') and immediately scopes it by its distinguishing feature — it returns the current `version` needed for optimistic concurrency. It is clearly separated from the nearest sibling by noting that get_issue_context returns this plus parent, siblings, comments and handoffs.

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 enumerates when to call it — before update_issue, transition_issue, assign_issue, move_to_sprint, rank_issue, link_issues, unlink_issues, delete_issue — and what to do with the result ('pass the `version` it returns'). It also names the richer alternative (get_issue_context) and the condition for preferring it, plus a caveat to read `working`/`touches` before changing what they touch.

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, yet the description adds substantial behavior beyond them: truncation order (oldest comments, then development items, then siblings) with `truncated: true`, the per-bundle random-token BEGIN/END USER CONTENT wrapping as a prompt-injection guard, and the `agent_live` Premium/agent-account prerequisite (D144). The `version` semantics for later update_issue/transition_issue calls are also spelled out. Nothing contradicts the read-only annotation.

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 statement is essentially reproduced three times — the title-length sentence, a near-verbatim repetition in the first description paragraph, and again as 'Call this before you start a card (and when you pick one up from someone else) ...'. The security-marker explanation is likewise stated twice. Front-loading is good, but a large fraction of the text is 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 no output schema, the description carries the full burden and does: it enumerates the returned sections, ordering rules (in-progress first), truncation policy, the USER CONTENT framing, and the follow-up action using `version`. Internal doc references (D179/D153/D182) are opaque but do not block 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 100%, so the three parameters are already documented; baseline would be 3. The description still adds real meaning on top: `max_chars` default 24000 with the 2000–200000 range and, crucially, what exceeding it does (drops oldest comments → development items → siblings, sets `truncated`). It also frames `version` as the value to pass onward, though that is an output field rather than a parameter.

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

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

The definition names a specific verb and resource — 'Everything about ONE card ... as one markdown text' — and enumerates the exact contents (fields, version, working/touches, parent, subtasks, siblings, linked cards, last 20 comments, development items, handoffs). It is clearly differentiated from near-siblings by naming them: get_docs_context as the analogous doc tool and list_comments / list_development / search_issues `parent` as the ways to fetch what was truncated.

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 when-to-use is stated twice with a concrete workflow: 'Call it before you start a card (and when you pick one up from someone else)', then read `working` of related cards before changing anything they touch, then start with ONE update_issue using the returned `version`. Exclusions/alternatives are also given for the over-`max_chars` case, routing to list_comments, list_development and search_issues `parent`.

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 read-only, idempotent, non-destructive safety. Beyond that the description discloses real behavior: a status with removing:true returns 409 column_removing if targeted, rollup/formula fields are read-only and surface in each issue's computed, targets the reader cannot open are skipped, depth 1, and that columns, fields, saved filters and template settings are web-app only with no tool for them. That is substantive context the annotations do not carry; it is only held to 4 by the sheer sprawl of the disclosure.

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?

Roughly a thousand words for a one-parameter read tool. It is front-loaded with a one-line summary, but everything after is an undifferentiated dump of spec references (D102, D129, D130, D131, D143) and template-by-template workflows, most of which matter only after the call returns and only for specific templates.

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 no output schema, the description does need to explain the returned shape, and it does so thoroughly: board_type variants, statuses/meaning/color/wip_limits, fields with their types, saved_filters as search_issues parameters, releases, votes. An agent can interpret the response without a schema. It loses a point because some included material (roadmap RICE formula derivation, feedback triage detail) is not needed to interpret or invoke this 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?

There is a single parameter and schema description coverage is 100% (pattern, length and example all documented in the schema). The description adds nothing about project_key itself, so the schema does all the work — baseline 3 is correct for this configuration.

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 first two lines state the specific verb and resource: fetch project.md with board type, workflow/statuses, custom fields, saved filters and the caller's own role. This is clearly distinct from siblings like get_doc, list_projects or get_issue_context. It stops short of 5 because the actual purpose statement is immediately swallowed by a wall of template-specific detail, so the agent must parse past a lot before it can act.

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

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

There is genuine conditional guidance embedded — 'Always take status ids from here — never guess them', 'when the user names one [saved filter], run search_issues with that query', the triage rule that agents move posts to Reviewing/Accepted/Declined only when the user asks. But none of it is framed as when to call get_project versus list_projects or get_issue_context; the guidance is about downstream tools the data feeds, not about this tool's selection.

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?

Even though the annotations already declare read-only, idempotent and non-destructive, the description adds a lot of behavior an agent cannot get from them: the Premium gate (403 plan_required with details.feature), admin-only people/unassigned fields, the 400 invalid_range condition for reversed or >366-day ranges, and how done counts are attributed (current assignee, rows plus unassigned sum). It also discloses the measurement limitation that only cards with a recorded first move count toward cycle time.

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, but the text is long and repeats itself — the 'measured n of m cards' / cycle_measured-of-cycle_total instruction appears twice, and the current-assignee attribution summing to done cards is also stated twice. The duplication costs space that could carry new 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?

There is no output schema, yet the description compensates by explaining the conditional fields an agent will see (people, unassigned, cycle_measured/cycle_total, prev, delta_*, better) and how to report them. For a read-only analytics tool, nothing an agent needs in order to call it or interpret the response 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 schema already documents all four parameters, but the description adds real meaning: the default window is the last 30 days, compare pulls the equal-length prior period, and people/unassigned are conditionally returned based on admin status rather than being inputs. It goes beyond the schema rather than restating it.

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 a specific verb and resource — flow numbers of a project — and enumerates the exact metrics (cycle time, lead time, throughput, WIP, stuck cards, bugs, releases) over a date range. It is clearly distinguishable from sprint- or company-level siblings by scope, though it never names get_company_insights or get_burndown as the alternatives an agent should consider.

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 usage rules: omit from/to to get the default 30-day window, pass from/to and compare only when the user names a range, and note that CSV exports are web-only. What is missing is explicit routing guidance for when an agent should prefer get_burndown or get_company_insights instead.

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 this as a read-only, idempotent, non-destructive operation, and the description adds important behavior: for non-release managers, gate items, baseline, scope history, and certain fields are omitted or nulled, and only gate_summary is provided. It also warns not to guess, round, or invent numbers and to name issue keys from reasons, which is valuable behavioral guidance beyond annotations.

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

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

The description is front-loaded and mostly purposeful, with the core scope, returned fields, member-view caveats, and tool boundaries clearly organized. However, it repeats the title as its opening sentence and restates the 'do not guess numbers' instruction twice, leaving some tightening possible.

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?

No output schema exists, so the description carries the full burden of explaining return content, and it does so well: status, features, checks, reasons, other, counts, gate_summary, and scope are named. It also explains the permission-dependent shape of the response and the limits of what an agent may do with releases.

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

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

Schema coverage is 100%, and the schema already documents project_key and release_id formats, including the R-n release id pattern. The description does not add parameter-level detail beyond the schema, so baseline 3 is appropriate.

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

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

The description states a specific resource and scope: one release and its readiness, feature by feature, computed from the board under D113. It clearly distinguishes this from release-listing or issue-level tools by focusing on a single release's readiness and returned fields.

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 to read this before answering release questions such as readiness, blocked work, or steering summaries. It also clarifies the boundary against related mutation tools: create_release and update_release are allowed for planned releases, but gate ticking, baseline locking, shipping, reopening, and deletion are not available to the agent.

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

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

Annotations already mark this as read-only, idempotent, and non-destructive, but the description adds substantial behavior: visibility filtering at read time, removed execution rows, 404 when nothing remains, role-specific access, test-summary restrictions, and one-year retention. It also discloses that the response is markdown with structured data attached and that cut lists end in 'and n more'. This is rich context beyond the annotations.

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

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

The description is front-loaded and well structured into purpose, workflow, access, and output expectations. However, it repeats the title sentence, the latest-of-a-kind instruction, and the 404 behavior multiple times, so not every sentence earns its place. It is readable but more verbose than necessary.

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?

There is no output schema, so the description carries the burden of explaining the return value; it does so by stating that the result is markdown with structured data attached and by listing the kinds of content included. It also covers permission filtering, 404 conditions, retention, and test-summary access. Nothing essential for correct invocation appears 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 `summary_id` pattern and format are already fully documented in the schema. The description adds only the workflow hint to pass the id returned by list_summaries; it does not add syntax or format details beyond the schema. Baseline 3 is appropriate when the schema carries the parameter documentation.

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

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

The description states a specific verb and resource: reading one summary by id, returned as markdown with structured data attached. It also distinguishes this tool from list_summaries by explaining that latest-of-a-kind requires list_summaries with limit=1 first. An agent can identify the tool's role 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?

It explicitly routes latest-summary lookups through list_summaries with `limit=1`, then says to pass the returned `id` here. It also gives permission-based conditions that lead to 404, so the agent knows both the intended workflow and failure boundaries.

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 already declaring readOnly/idempotent/non-destructive, the description adds substantial extra context: thread order (oldest first), message kinds (customer/staff/system), attachment handling (file names only, opened in the web app), field meanings for `following` and `reopen_until`, company-wide visibility, and how AI-agent writes are labelled. This is behavior beyond what any annotation conveys.

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 lead sentence duplicates the title verbatim, and the attachment/web-app point is made twice ('Attachments show as file names only — people open them in the web app' and 'Text only: files are attached in the web app'), so not every sentence earns its place. The content is otherwise dense and reasonably front-loaded, but the redundancy costs it.

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?

There is no output schema, so the description properly carries the return-shape burden: it explains the thread, the message kinds, how attachments appear, and the meaning of `following` and `reopen_until`. An agent has everything needed to call it and interpret the result.

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 `case_id` parameter is fully documented in the schema (pattern, ULID, spec reference), so the schema does the heavy lifting. The description adds no additional meaning about the parameter itself (no format examples or ID-sourcing guidance), making the baseline 3 correct.

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 concrete verb and resource ('One case ... with its whole thread, followers and context') and immediately distinguishes support cases from issues, naming the sibling tools an agent might otherwise confuse it with. An agent can tell exactly what this retrieves 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?

Gives an explicit when ('user wants help from the BoardMark team or reports a problem with BoardMark itself — a bug, signing in, billing, a feature request') and an explicit when-not ('never for the user's own project work') with the alternative named (create_issue, search_issues). Nothing is left to inference.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so safety is covered. The description adds real behavior beyond that: every member of the token's company can see and answer every case, replies land in the case thread and also reach followers by email, attachments are web-app only, and agent writes are labeled 'via AI agent'. Much of this is support-case context rather than this specific summary's behavior, keeping it just below 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?

Front-loaded with the purpose and the two metric definitions, then usage, which is the right order. It is somewhat long and includes tangential material (email delivery of replies, web-app file attachments) that does not help call this particular 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 no parameters and no output schema, the description carries the burden and does define the two counts it returns plus visibility scope, which is most of what an agent needs. It never states the concrete response shape (e.g., a two-field count object) or whether counts are scoped by filters, leaving a small gap.

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

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

There are no input parameters, so the baseline is 4, but the description goes further and defines the semantics of the values it returns ('waiting_customer' = cases the BoardMark team answered and awaits the company; 'open' = cases not closed) — meaningful interpretation help given no output schema exists.

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 precisely what the tool returns — a company-wide count of cases waiting on the customer versus cases still open — and even defines each metric. It distinguishes itself from get_support_case (read a thread) and from issue tools, so an agent can identify it 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 routing: use support cases when the user wants help from the BoardMark team or reports a bug/sign-in/billing/feature request, and 'never for the user's own project work (that is issues: create_issue, search_issues …)'. Both the when and the when-not are named, along with the alternative tool family.

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 readOnlyHint=false / idempotentHint=false; the description goes far beyond them by disclosing side effects (it sets the installment's invoice_no and invoiced_at, marking it invoiced), that numbers are automatic and permanent, that both PDFs are attached to the deal, and the two named 409 outcomes with their remedy (seller_incomplete → tell a company admin). That is exactly the mutation context 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?

Front-loaded and information-dense, but the description is roughly 250 words and the second paragraph substantially restates the first (customer data, VAT mode, no tax invoices, automatic numbers, seller_incomplete 409). The duplication is the main structural flaw; the tool could say the same thing in about half the length.

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?

No output schema exists, and the description compensates by describing the return value (attachment_id for th + en files, plus paths) and routing to get_download_url. Given 13 params with nested customer/lines/payment objects, the description covers the operational prerequisites and failure modes an agent needs before calling it.

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 69% and the description adds real meaning for the tricky parameters: kind semantics per enum value, installment_key's role for billing_note, and revise_of's -R2 re-issue behavior. It does not touch payment, valid_until, or the note/note_en fields, but the schema already carries those descriptions, so the gap is minor.

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 (issue) and resource (quotation / billing note / receipt PDF, th + en) scoped to a Sales & Billing deal, and explicitly distinguishes itself from a tax invoice ('BoardMark issues no tax invoices'), which is the most likely confusion with a sibling/finance tool. An agent can tell exactly what this creates versus list_sales_documents or get_download_url.

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 selection rules: quotation = whole deal, billing_note = one installment (requires installment_key), receipt = paid installment only (else 409 installment_not_paid). It also adds a mandatory pre-step ('ask the user for customer name, address, tax ID... never invent them; show the lines and VAT mode for approval') and names the follow-up sibling (get_download_url) for retrieving the PDFs.

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 by explaining that the inverse link is written on the target issue, including cross-project targets, and that `delivers` writes no inverse. It also discloses error behavior (403 link_target_forbidden, 404 release_not_found, 400, 409 version_conflict) and the post-condition visible via get_issue.

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-loaded with the primary action, then dense but purposeful sections on inverse links, `delivers`, errors, and version conflict handling. It is long and dense as a single block, but nearly every sentence carries operational meaning; headings or bullets could improve scanability.

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 non-idempotent write tool with no output schema, the description covers the critical gaps: inverse-link side effects, cross-project permission boundaries, `delivers` release semantics, error handling, version-conflict recovery, and how the result is later observed via get_issue.

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?

Although schema coverage is 100%, the description adds substantial semantic value: `id` accepts either an issue key or `KEY/R-n` depending on `type`, `version` must come from the latest read, and `reason` is optional but recommended for agent accounts. These are behavioral constraints the schema alone does not fully convey.

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 precise verb and resource: "Add a link from this issue to another." The description immediately adds scope: cross-project constraints, inverse-link behavior, and the `delivers` special case, so an agent knows exactly which operation this performs versus unlink_issues or other write tools.

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

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

Provides strong conditional guidance: `id` must be in this project or another project of the same company, cross-company links do not exist, `delivers` requires `KEY/R-n` instead of an issue key, and mismatch is a 400. It does not explicitly name alternatives like `unlink_issues`, which keeps it from 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 only declare the generic read-only/idempotent safe-read profile; the description adds substantive behavior on top: that attachments referenced in descriptions and comments are included, that only finished uploads appear, that the list is newest-first, and what an empty result means. It also explains the `uploaded_by` vs `agent_token_id` distinction, which the agent cannot get from 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?

Front-loaded with the core statement and the follow-up routing, and the field list earns its place since there is no output schema. Minor waste: the first sentence restates the title verbatim, and `uploaded_by`/`agent_token_id` are explained twice (once in prose, once in the item list).

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 no output schema, the description fully documents the return shape (attachment_id, path, filename, content_type, size_bytes, created_at, uploaded_by, agent_token_id) plus ordering and edge-case behavior. Nothing an agent needs to call it or interpret results 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% with patterns and examples for both required parameters, so the baseline is 3. The description only implies issue scoping and adds no format or constraint 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?

States a specific resource (every file attached to one issue) with an explicit ordering (newest first), a permission scope (anyone who can read the issue), and inclusion rule (files from description and comments). An agent can immediately distinguish this from get_download_url, read_file, and delete_attachment.

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 says when to use it ('to see which files an issue has before reading or referring to them') and routes to the correct alternative for the follow-up step (get_download_url with attachment_id). It also closes the ambiguity of an empty result ('an empty `items` means the issue has no files').

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, yet the description still adds substantial behavior beyond them: page size and ceiling, cursor chaining via `next_cursor`, the fact that newest comments sit on the final page, and that deleted comments remain in the listing with empty bodies but intact replies. That last point in particular would be surprising and wrong to 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?

Front-loaded with the essential ordering and pagination rules before the field-level detail, and nearly every clause earns its place. The single dense paragraph makes the frontmatter semantics harder to scan than a short bulleted breakdown would, which keeps it off a 5.

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 no output schema, the description carries the full burden of explaining return values and does so thoroughly: `frontmatter.seq`, `reply_to` vs `in_reply_to` for one-level thread grouping, `version` for downstream edits, `updated_at`/`updated_by`, and the deleted-comment representation. An agent can read and reconstruct threads correctly from this alone.

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 75% and already documents `cursor` and the issue/project key formats, so the baseline is 3. The description goes beyond by linking the output `next_cursor` to the input `cursor` and by restating the 50-default / 200-max pagination contract, which makes the two undocumented-ish parameters unambiguous in practice.

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 (list comments) plus the scope and ordering (for one issue, oldest first). It is immediately distinguishable from the comment-mutating siblings add_comment, update_comment, delete_comment, and from get_issue / get_issue_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 concrete operational guidance: 50 per page, limit up to 200, page until `next_cursor` is absent, and the non-obvious warning that the newest comment is on the LAST page. It also tells the agent to skip `deleted: true` entries when reading a thread and points to update_comment/delete_comment for the version field. It does not explicitly name a sibling alternative to use instead in any condition, 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 already declare readOnly/idempotent/non-destructive, yet the description still adds real value: data provenance (project admins' connected GitHub/GitLab repos), a 20-commit cap, and a thorough list of legitimate empty-result conditions (no connected repo, no match, Free plan, paused integration). It does repeat 'read-only; changes nothing', which the annotations already fully 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?

The purpose is front-loaded, but it is stated three times: the title is pasted verbatim as the opening line, then restated as 'MCP tool list_development', then again as 'Development (D153): lists the merge / pull requests...'. The repetition of the read-only claim (also in annotations) and the duplicated spec reference crowd out otherwise useful detail.

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 two-parameter read tool with no output schema, the description covers origin of the data, the returned shape, the commit cap, and every empty-state explanation an agent would need to respond without speculating. Sufficient to call and interpret correctly.

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

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

Schema coverage is 100% and both parameters are documented with patterns and examples, so the schema already does the heavy lifting. The description adds the useful implication that issue_key matching is substring-based in branches/titles/commit messages, but no additional syntax or format detail beyond that.

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 a specific verb (lists) and resource (pull/merge requests with state and CI, plus latest commits) scoped to an issue key, and enumerates the exact returned fields. Nothing in the sibling set (get_issue, list_comments, list_attachments) covers cross-repo development artifacts, so the boundary is clear.

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

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

It gives concrete operational guidance: report state/CI/branch/link as returned, and if the result is empty, tell the user nothing is linked and suggest embedding the issue key in the branch, PR/MR title or commit message. It also notes that connecting repos and auto-move rules are admin responsibilities in the web app. What it lacks is an explicit pointer to a sibling alternative for adjacent needs.

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, non-destructive and closed-world, so the safety profile is fully covered structurally. The description adds useful scoping context (it exposes the markdown tree with issues/, sprints/, views/), but says nothing about what happens with an invalid or missing path, whether output is flat or nested, or ordering.

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 the key fact front-loaded; the second sentence earns its place by naming the tree contents. Minor waste from restating the title verbatim in the first sentence.

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 no output schema and one undocumented parameter, the description should explain path semantics and the shape of the returned listing, and it does neither. An agent can guess at a root listing but cannot reliably navigate to issues/ or sprints/ from this text.

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 only 50% – project_key is documented in the schema, but path has no description and only a default of empty string. The description does not clarify whether path is relative to project root, whether it needs a trailing slash, how to address the named subdirectories, or that an empty path means root, so it fails to compensate for the coverage gap.

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?

Specific verb plus resource ('List a directory of the project tree') with a follow-up sentence naming the md tree and its top-level entries. It's clear what the tool does, but it doesn't distinguish itself from adjacent siblings like read_file, list_docs, or get_doc, which an agent could plausibly pick instead.

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

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

There is no when-to-use guidance, no mention of when to prefer read_file or get_doc, and no prerequisites. The second sentence gives content examples but not selection criteria, so the agent must infer routing from the name alone.

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

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

Annotations already declare read-only, idempotent, non-destructive, so the safety profile is settled; the description goes well beyond by disclosing the 403 doc_admin_only failure for members, the handoff lifecycle (open → acknowledged → closed), the meaning of `for_me`, and a security rule that notes/handoffs/comments are information rather than executable instructions. That is exactly the context annotations cannot carry.

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 and the call-before-working directive are front-loaded in the first two sentences, and the return-field catalogue is justified because there is no output schema. It is dense and leans on parentheticals (D76/D182 tags, long nested asides), which costs a point but no sentence is genuinely empty.

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 no output schema, the description carries the full burden of describing return shape and does so item by item (`kind`, `slug`, `title`, `version`, `size_bytes`, `updated_at`, `updated_by`, `updated_by_agent`, plus handoff-specific `status`, `to`, `for_me`). Nothing an agent needs to call or interpret the result 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, but the description adds semantics the schema's enum list does not: what each `kind` value actually contains (rules vs. information), who can write it, and what `for_me`/`read_first` mean for the consumer. It largely restates `include_deleted` as the schema already words it, which keeps this just short of a 5.

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 ('List the project docs — brief, working notes, handoffs — and the company brief') and enumerates exactly what is returned. It also implicitly distinguishes from siblings by noting `slug` is passed to get_doc, so an agent knows this is the listing endpoint, not the fetch-one endpoint.

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?

'Call this (or get_docs_context) BEFORE you start working on a project' gives explicit timing and names the alternative. It further routes the agent: read `for_me` handoffs then call acknowledge_handoff, and use restore_doc_version for deleted docs. When-to-use and when-to-do-something-else are both 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?

Rich beyond the annotations: it discloses that the tool is served locally by board-mcp (no board-core route, direct call 404s), that data comes over `/ws` with the user's own token, 30-day retention, agent-token reads owner's inbox, and 503-implies-retry. It stays at 4 rather than 5 only because much of this is restated redundantly across paragraphs instead of stated once cleanly.

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?

Badly bloated: the title text is repeated verbatim at the start, the 'call this when a session starts...' sentence appears twice, the prompt-injection warning about `text` appears twice, and the agent-token ownership note appears twice. The genuinely useful facts (404 behavior, 30-day retention, 503 retry) are buried in the duplication.

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

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

Despite no output schema, the description enumerates every returned field (`id`, `at`, `kind`, `project_key`/`issue_key`, `who`, `via_agent`, `text`, `read`), explains paging, retention, and the error path. Nothing an agent needs to call and interpret the result 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 67% and covers `before` and `unread_only`, but the description adds the crucial paging recipe ('page with `before` = `next_before`') and clarifies `unread_only: true` for new entries. `limit` (default 20, max 30) is left undocumented in both places, so it misses the top mark.

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 ('your notifications ... as an agent reads them') and enumerates exactly what kinds of events appear (assignments, @mentions, replies, status changes, handoffs, project access). It also implicitly separates itself from read_inbox, which it names as the marking counterpart.

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?

'Call this when a session starts and whenever you finish a card' gives explicit trigger conditions, and the routing to read_inbox for marking entries read distinguishes the sibling pair clearly. It also disambiguates overlap with get_project `docs.open_handoffs_for_me` / list_docs `for_me`.

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, and the description adds behavior annotations cannot express: default filtering to open (non-done) issues unless include_done is true, cursor pagination, the returned item shape with project_key/project_name, Sales & Billing installment inclusion with flags, and the agent-token (agt_) assignment 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?

Sentences are dense and front-loaded, leading with the headline behavior and the alternative tool. The main inefficiency is the first sentence restating the title verbatim and the triple-nested D-reference parentheticals, which cost space without adding selection value.

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

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

No output schema exists, but the description enumerates the returned fields, the added project_key/project_name, pagination via next_cursor, and the installment flags — everything an agent needs to consume the result correctly. Defaults and the agent-account edge case are also covered.

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 only 33% (limit and include_done have no schema descriptions), but the description compensates for include_done ('Open issues only ... unless include_done: true') and explains cursor/next_cursor pagination. The limit parameter's meaning and its 50/200 bounds are left entirely to the schema, so it falls short of a 5.

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 a specific verb+resource (list open issues assigned to you), states cross-project scope, ordering, and the Sales & Billing installment extension. It also explicitly differentiates from search_issues and get_issue, so an agent can pick it out from 70+ siblings 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?

It states when to use it ('What's on my plate?') and when not to: use search_issues when the user means one project or needs other filters, and call get_issue before changing any listed issue. Exclusions and the pre-mutation step are both explicit.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior, but the description adds substantial context beyond them: inclusion rules for members/admins/company-wide seats, exclusion of deleted/deactivated people, agent-account behavior, paused/stopped status, sorting, and notification implications. No annotation contradiction is present.

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 purpose and audience, which is good, but it is very long for a one-parameter read tool and repeats usage details around naming, mentions, and exact ids. Much of the detail is useful, but several sentences could be tightened without losing meaning.

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 no output schema, the description carries the burden of explaining the returned population and important fields such as user_id, name, via: company, and agent fields. It also explains exclusions and sorting, making the definition complete enough for an agent to use the result 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?

The schema has full description coverage for the single project_key parameter, so the description does not need to explain its format or pattern. It reinforces project scoping with 'one call per project' and project-wide access context, but adds little direct parameter semantics beyond the schema baseline.

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

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

The description states a specific verb and resource: listing people who can open a project, including members, company admins, and company-wide access users. It clearly distinguishes the result from related tools like list_watchers by defining the access set and its use for mentions and assignments.

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 explicit usage contexts: resolving issue user ids to names, finding ids for @mentions or assignments, and using exact ids from this result. It also states alternatives and constraints: adding/removing members is web only, one call per project is enough, ask the user when names collide, and missing people cannot open the project.

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 openWorldHint=false, and the description correctly stays consistent with a safe read. It adds genuine context beyond annotations: pagination mechanics via next_cursor, the meaning of done_issues (done-category statuses), active_sprints only existing for scrum with possible multiple running sprints and empty on kanban/pipeline, and updated_at being nullable. However, it says nothing about ordering, default page size (limit is only in the schema), or whether membership scope changes results.

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-loaded with purpose, then pagination, then the stats trade-off, then the docs pointer — a sensible ordering with no filler sentences. The stats enumeration is dense and long, but each field named carries real information; minor cost is that the single paragraph is hard to scan.

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

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

No output schema exists, so the description carries the return-shape burden and does so: it explains the base payload (project keys), the optional stats sub-object field by field, and the null case for updated_at. Combined with pagination and the docs follow-up, an agent has everything needed to call it correctly and interpret the result.

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 67%, and the description compensates well for the undocumented parts: cursor is explained as coming from the previous page's next_cursor, and stats is unpacked far beyond the schema's one-liner including the full shape of each stats item. limit remains unexplained in both places, though its 1–200 bounds and default 50 are self-documenting in 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 first line states a specific verb and resource with scope ('projects you are a member of'), which cleanly separates it from get_project (single project), get_project_insights, and the other list_* siblings. The follow-on line establishes that the returned project keys are the currency used by every other tool, making the tool's role in the workflow 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?

Explicit when-to-use: pass stats:true for a portfolio overview and specifically 'instead of searching each project', and leave it off when only keys are needed — a stated exclusion, not just a suggestion. It also names the follow-up path (get_project docs.read_first / get_docs_context) before starting work, so the agent knows the next call in the sequence.

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 read-only/idempotent safety, but the description adds real value: the status enum meanings (not_ready, at_risk, ready, released), the fact that counts are derived from the board by fixed rules, and a concrete 403 feature_disabled remediation path. It stops short of describing return shape or ordering, but that is a minor gap against 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?

The opening sentence is a verbatim repeat of the title, which wastes the most valuable front-loaded position. The remainder is dense and earns its place, but the title duplication is avoidable bloat.

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 no output schema, the description carries the burden of explaining what is returned, and it does reasonably: readiness status values and derived counts. Only the state filter's semantics and result ordering are left implicit.

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 50%: project_key is fully documented in the schema, while the state enum has no description. The description's 'planned ones by default' hints at the state default but never explains planned vs released vs all, so it only partially compensates.

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 a specific verb+resource (releases of the project) and adds scope detail (readiness, D113, planned by default). It is distinguishable from get_release/create_release by the plural listing framing, though no sibling is named 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?

'Planned ones by default' implies the state filter and when the default applies, and the 403 branch tells the agent what to do on failure. However, there is no explicit guidance on when to choose this list tool over get_release or how 'all'/'released' should be selected.

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

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

The annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false. The description adds substantial behavioral context beyond that: item fields such as number, kind, status, latest, attachment IDs, stale quotation semantics, seller.complete meaning, and the 409 non-sales-deal error.

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 but significantly repetitive: the first paragraph and the later 'Sales documents (D149)' paragraph restate the same resource set, fields, attachments, download route, and stale semantics. This duplication wastes space and makes the definition less crisp than it could be.

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?

Although there is no output schema, the description explains the returned item shape, attachment IDs, status values, stale quotation behavior, seller.complete precondition, and error case. For a two-parameter read-only list tool, this gives the agent enough to invoke and interpret it correctly.

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

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

Schema description coverage is 100%, and the schema already documents both required parameters with patterns and examples. The description adds only the high-level instruction to give the deal key, not syntax or constraints beyond the schema, so the baseline 3 is appropriate.

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

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

The description identifies the exact resource set: quotations, billing notes, and receipts issued for a Sales & Billing deal, newest first, including installments. It is clearly a retrieval/list operation for sales documents, but it does not explicitly contrast itself with the sibling issue_sales_document tool, so it falls short of a 5.

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

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

It tells the agent to supply the deal key and documents a 409 when the target is not a Sales & Billing deal, which gives some usage context. However, it does not explicitly say when to choose this tool over get_issue, issue_sales_document, or other related tools, leaving the main selection guidance implied.

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 adds behavior annotations cannot carry: that `state=active` can return multiple sprints due to parallel sprints or a disabled switch, and that the returned `version` is a required input for downstream mutation tools. It does not describe ordering or pagination, which keeps it below 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?

Four short sentences, front-loaded with the purpose, then the downstream contract, then the usage caveat. Nearly every sentence earns its place. The leading "List sprints." restates the title, which is a minor redundancy.

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 no output schema and no annotations covering return shape, the description carries that burden and does partially: it names the `version` field and warns about multiple results. It does not enumerate other returned fields (name, dates, state), so an agent still learns the record shape only by calling. Adequate but not fully complete.

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

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

Schema coverage is 50% — `project_key` is documented but the `state` enum values are bare. The description compensates by explaining the semantics of `state=active` (multiplicity, causes), which is the non-obvious value of that parameter. `planned` and `closed` are left unexplained and scope-limiting behavior of project_key is not addressed.

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 ("List sprints") and immediately frames the result: each sprint carries its `version`. It distinguishes itself from siblings implicitly by naming what it feeds (update_sprint, close_sprint) rather than by contrasting with list_projects or get_burndown. Clear purpose, but sibling differentiation is indirect.

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 real routing guidance: tells the agent that starting a sprint is NOT a tool and instead the user presses Start sprint, so the agent should surface that to the user rather than look for a tool. It also warns to never assume a single active sprint. It does not say when to prefer list_sprints over get_burndown or list_projects, but for a list tool with an obvious scope that gap is minor.

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?

Well beyond the readOnly/idempotent annotations, it discloses the authorization model (project members only, 404 for non-members; company_id must equal the JWT company; admins see all exec reports, other members only those they received), error codes (400 validation_failed, 400 on kind/scope mismatch), retention (1 year), plan availability, and that test sends are excluded. This is exactly the behavioral context 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?

Front-loaded correctly with scope and the either/or rule, but the final paragraph largely re-states the opening paragraphs (newest first, no content, one-of-the-two, limit=1 → get_summary), so a meaningful fraction of the text does not earn its place. The title is also repeated verbatim as the first sentence.

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?

There is no output schema, and the description compensates by saying rows are SummaryListItem with no sections and that paging uses next_before from the previous page. Access rules, error conditions and retention are all covered; only the SummaryListItem field set itself is left by name only.

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 80% and the enum for kind is already documented, so the schema carries most parameter detail. The description adds the cross-parameter constraint that exactly one of project_key/company_id is required and that kind must belong to the chosen scope — semantics the schema's per-field descriptions only partially convey.

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 concrete verb and resource ('the summaries that were sent, newest first'), names both scopes (project archive vs. company executive reports), and contrasts implicitly with get_summary by noting rows carry no content. An agent can distinguish this from get_summary and list_* siblings 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?

Explicitly says to give exactly one of project_key or company_id, and routes to the alternative: 'To read the newest summary of a kind call this with limit=1, then get_summary with the returned id.' It also states exclusions (settings, previews and test sends are web only), so the agent knows what this tool will never return.

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 (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond: internal notes are never counted or shown, pagination via cursor/next_cursor, visibility rules ('every member of the token's company sees and can answer every case'), reply delivery (thread + email followers), a text-only limitation, and that agent writes are labelled 'via AI agent'.

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-loaded with purpose and the pre-check heuristic before the denser reference material (item fields, status glossary). Dense and every paragraph is useful, but it is long and the title sentence is repeated verbatim at the top, adding minor redundancy.

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?

No output schema, yet the description enumerates returned fields and their meaning (id vs number, status values with lifecycle notes), describes filtering defaults, pagination, and visibility/write-side behavior. Nothing needed to call it correctly is missing.

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

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

With 25% schema coverage the description carries most of the load and does so well: scope=mine meaning, state=open/closed semantics and defaults, and cursor/next_cursor paging are all explained beyond the raw schema. The one gap is `limit`, whose default and ceiling are left to the schema, so it falls short of fully compensating.

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 (support cases) with scope qualifiers (company-wide, any member, newest activity first) and immediately distinguishes the domain from issues via 'Support cases = asking the BoardMark team for help.' An agent can tell this apart from get_support_case and search_issues 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?

Explicit when-to-use ('when the user wants help from the BoardMark team or reports a problem with BoardMark itself'), explicit when-NOT ('never for the user's own project work — that is issues: create_issue, search_issues'), and a pre-condition naming an alternative action ('Check here before opening a case ... then reply there instead').

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 and closed-world, so the safety profile is covered. The description goes beyond them usefully: it explains that watchers are email recipients, that only users who can still open the project appear, and that watching is personal state with no version and no appearance in history or the md file. It stops short of describing the shape of the returned entries.

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 content is useful but redundant: the opening line repeats the tool title verbatim including '(spec D92)', and the notion of 'who gets emails besides its assignee and reporter' is stated twice. The '(spec D92)' reference consumes the highest-attention position without helping an agent decide anything.

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?

There is no output schema, so the description must carry the return semantics, and it does: it says a list of people is returned, applies a visibility filter, and notes the `watching` flag for the token's own user. It does not say what fields identify each watcher (name, id, email), which is the remaining gap.

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

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

Schema description coverage is 100%, and both issue_key and project_key are documented with patterns and examples in the schema itself. The description adds nothing about either parameter, 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 concretely states what the tool returns: the set of people who receive this issue's status-change/comment emails, with 'only people who can still open the project are listed' pinning down the filtering rule. The verb 'list' is never used, so the retrieval framing has to be inferred from the 'who watches' phrasing, and the closely related siblings watch_issue/unwatch_issue are never contrasted.

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 only implied: an agent can infer it should call this when it needs to know who gets notified about an issue. There is no explicit when-to-use statement, no exclusions, and no pointer to watch_issue/unwatch_issue, which are the obvious neighbouring operations in the sibling list.

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

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

Annotations only declare it as a non-destructive, non-read-only write; the description goes well beyond that with permission rules (members, release managers, project admins; viewers 403), a prerequisite failure mode (400 for a missing/already-released target), cascade semantics (an epic's children follow unless they name another release), and scope-history side effects once the baseline is locked. The 409 version_conflict recovery protocol is spelled out with `details.current` / `details.current_version` and an explicit 'never overwrite blindly' rule.

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-loaded and generally well organized, but the title sentence is repeated verbatim as the first line, and the 'after the release's baseline is locked / kept in the scope history' idea is stated twice in near-identical wording. Tightening those duplicates would cut noticeable length without losing 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 no output schema and a 5-parameter write tool that cascades to epic children, the description covers prerequisites, permissions, error paths and recovery, which is most of what an agent needs. It never says what a successful response contains (e.g. the new version), leaving that to be inferred from the 409 guidance.

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 80%, so the baseline is 3; the description adds real meaning on top by tying `version` to a mandatory read-before-write flow and explaining the `release: null` removal case and the timing of `reason` relative to the baseline lock. It doesn't add format or identity detail for `project_key`/`issue_key` beyond what the schema already documents.

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 — put an issue (or an epic with its children) into a release, or take it out via `release: null`. It also positions itself against siblings by describing the relationship to `update_issue` and routing bulk work to `add_to_release`, so an agent can distinguish it without opening other 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 preconditions (the release must exist and not be released yet; call `get_issue` first and pass its `version`), an explicit alternative for the bulk case ('use add_to_release … instead of calling this once per issue'), and guidance on when to supply `reason`.

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

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

The description adds substantial behavioral context beyond the annotations: it marks the operation as a WRITE, explains that version must come from the latest read, and describes the 409 version_conflict recovery flow. This is exactly the kind of concurrency and safety guidance an agent needs 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?

The description is reasonably compact and front-loads the main constraint and write behavior. However, it repeats the title almost verbatim and then repeats 'Scrum projects only' in the next paragraph, which is mild redundancy.

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 Scrum-only mutation with no output schema, the description covers the essential constraints, nullable sprint behavior, optimistic-lock version requirement, and conflict recovery. Nothing critical for correct invocation appears to be 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 already high at 80%, and the description adds useful semantics for the most nuanced parameter: sprint is an S-n ID or null for backlog, and only planned or active sprints are valid. It also clarifies where version should come from.

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

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

The description states a specific verb and resource: moving an issue into a sprint or to the backlog, limited to Scrum projects. This is clearly distinguishable from sibling tools like update_sprint, close_sprint, and move_to_release.

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