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.