Retasc

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

Adds substantial context beyond the annotations: the bearer-token model means no invite code is ever held, authorization is by id match, and the side effect is asymmetric (grants the human a membership, leaves the calling key's org/project scope untouched). These are non-obvious consequences that the readOnly=false/destructive=false flags 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?

Five tight sentences, front-loaded with purpose, then constraints, then effect. The internal ticket reference (RTSC-686) is noise that earns nothing for an agent, but otherwise there is little 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?

Covers effect, authorization, consent and discovery path, which is what an agent needs to act safely. With no output schema, it stops short of saying what a successful call returns or what an invalid/expired invite looks like.

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 description essentially restates the schema ('slug or name, from whoami's pendingInvites'). 'As they'd say it' hints at fuzzy matching tolerance, but there is no detail on accepted forms or failure behavior for an unmatched org name.

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 ('Join YOUR HUMAN to an org that invited them') and makes the acting principal explicit, which cleanly separates it from invite_member, list_invites and revoke_invite in the sibling set. An agent can tell what this does and for whom 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 ('only invites ADDRESSED to your principal'), an explicit when-not ('never call this unprompted', pasted links go in a browser instead), and routes to whoami for discovering what's waiting. The human-consent precondition is stated as a hard rule rather than 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 non-read-only, idempotent, non-destructive, and the description adds real behavioral context beyond them: dependency cycles are rejected, and billing refusals return a `tellHuman` payload with explicit instructions not to silently degrade. It does not state whether the link applies immediately or what other error modes exist, but the failure-mode disclosure is unusually useful.

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 type semantics are front-loaded, and the billing paragraph, while long and somewhat repetitive, covers a genuine failure mode. A sentence could be trimmed in the billing warning 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?

For a 3-required-param mutation with no output schema and zero param coverage, the description covers link types, cycle rejection, and billing refusal, which is solid. It leaves the source/target directionality and any duplicate-link behavior unaddressed, which an agent needs before calling 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 0% for all three required params. The description restates the enum values already present in the schema but never explains the direction of the relation — whether `sourceId` blocks `targetId` or vice versa — which is the single most error-prone semantic for this call, nor what kinds of IDs are accepted.

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 ("Link two issues") and enumerates the four link types, so the resource and action are unambiguous. It does not name a sibling to distinguish from, notably remove_relation, so it stops short of full sibling differentiation.

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

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

Inclusion of `blocks`/`blocked_by` as the dependency graph that drives blocking and the cycle-rejection rule gives implied guidance on when to pick those types. There is no explicit guidance on when to use this vs `remove_relation`, or what permissions/preconditions are needed to link two 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?

Though annotations already mark this read-only and idempotent, the description adds substantial non-obvious behavior: owner/admin gating with `costUsd` null otherwise, members seeing only their own slice, `limit` being issues *scanned* rather than returned, the inline size cap truncating pages early, and the 'one read per call' billing model. These are traits an agent cannot infer from schema or 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?

Correctly front-loaded with the core purpose, but the first sentence is a run-on that enumerates roughly twenty field names inline. Since there is no output schema that enumeration does carry return-shape information, yet it bloats the opening and makes the key operational rules (paging, billing, scope) harder 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?

For a 10-parameter, no-output-schema, permission-sensitive list tool, the description covers return fields, scope restrictions, pagination termination, truncation caveats, and billing. An agent could call and page this correctly without further information.

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 meaning: `by` determines which of three timestamps places an issue in the window, `limit` counts scanned rather than returned issues, and `cursor` must be replayed with identical other arguments. Only `tz`, `days`, and `person` are left to the schema alone.

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 (per-issue rows) and frames it precisely against the sibling: 'THE PER-ISSUE FACTS BEHIND THE ANALYTICS NUMBERS', distinct from the aggregate `analytics_overview` and from `list_issues`. The use case ('building its own dashboard or checking a figure') tells an agent exactly what output shape to expect.

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 clear context (dashboard-building, figure-verification) and explicit paging instructions ('Follow `page.cursor` ... until `page.done`'), plus the scope rules for project/allProjects/person. It does not explicitly say when to prefer `analytics_overview` or `list_issues` instead, so routing to alternatives is implied rather than stated.

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 the readOnly/idempotent annotations, it discloses authorization failures (FORBIDDEN for member keys widening scope), paywalled sections (money and roster are owner/admin), the response envelope (asOf, timezone, window, units, per-metric definitions), pagination via `page.cursor` with identical arguments, and billing ('one read per call'). That is far more than the annotations 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?

Well front-loaded — purpose first, then explicit WINDOW/SCOPE blocks — and capitalized labels help scanning. The metric-by-metric enumeration (e.g. 'Retasc fee by outcome, labour, and who is behind each bucket') is dense and partly redundant with the `sections` list, but with no output schema it earns most of its space.

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 12-parameter, zero-required, output-schema-less analytics tool, this covers everything an agent needs: what is returned, defaults, timezone and window rules, permission gates, pagination, and cost. Nothing material about invoking it correctly 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% (baseline 3), but the description adds real semantics the schema lacks: it enumerates the valid `sections` values even though the schema has no enum, explains the days-vs-from/to precedence and the bucket-unit behavior per window, and spells out that `maxBars` coarsens and snaps outward rather than refining. It also explains the `bucketFrom`+`bucketTo`+`person` interaction.

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 framing — every metric the Dash analytics page shows, computed by the same code — and enumerates the actual sections (pipeline, series, fleet, queue, review, money, findings, people) so the agent knows exactly what comes back. Sibling `analytics_issues` is not named, but the breadth described here is unmistakably the org/project overview rather than an issue-level report.

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: 'Use it when a human asks how their fleet or project is doing; build the chart yourself from what it returns' — which also tells the agent it produces data, not rendered output. It adds hard preconditions for widening scope (owner/admin or FORBIDDEN) but never names a sibling as the alternative for narrower questions.

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

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

Annotations already establish that this is a read-only, idempotent, closed-world operation. The description adds substantial beyond-annotation context: owner authority is required for the billing block, unauthorized callers get only the usage meter with a `note`, Xenarch degradation is surfaced as `payments: null` plus `paymentsError`, historical payment links are fanned out, and reading billing is not charged.

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 value is front-loaded in the opening phrase, and the dense sentence structure packs in useful return-shape and failure-mode details. It is long and somewhat paragraph-heavy, but almost every clause carries operational 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 and zero input parameters, the description carries the burden of explaining what comes back. It does so thoroughly, covering the full billing block, the degraded Xenarch path, the non-owner partial result, and the absence of billing charges for the read.

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

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

The tool takes zero parameters, so there is no parameter semantics to explain. A baseline of 4 is appropriate because the description does not need to compensate for any schema gaps.

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 resource — the org's whole billing picture — and enumerates the returned components: subscription, caps, money states, charge ledger, confirmed on-chain payments, and usage meter. This is far beyond restating the title and lets an agent recognize the tool's scope immediately.

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 clearly states the authority prerequisite for the full billing block and explains what non-owner callers receive instead. However, it does not explicitly compare this tool to the sibling `usage_summary`, nor does it say when to choose the narrower usage-only tool versus this full billing view.

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 the readOnly/idempotent annotations, the description discloses lease renewal semantics, proxy vs no-proxy behavior, reconnection effects, status meanings, and the guarantee that this call never renews anything. That is substantial behavioral context an agent needs before trusting the result.

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

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

The core purpose and commit-gate warning are front-loaded, and most detail earns its place because there is no output schema and the lease semantics are complex. It is still very dense and could be more structured, but it is not repetitive filler.

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

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

Given no output schema, the description fully explains the returned fields, statuses, `heldBy`, renewal timestamps, `renewedByYourCalls`, and `reclaimWouldMove`. It is complete enough for an agent to interpret and act on the response.

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 one parameter and schema description coverage is 100%, so the schema already documents `identifier`. The description adds surrounding lease context but does not add much specific meaning about the `identifier` parameter itself, 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 check with a clear resource: whether THIS session holds an issue/RTSC lease. It distinguishes itself from claim_issue and heartbeat by explaining that it is read-only, never renews anything, and reports the holder rather than changing it.

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: before committing or opening a PR on an `rtsc-NN/` branch, verify the session holds RTSC-NN. It also says when to re-claim via `claim_issue`, when not to, and how to interpret `renewedByYourCalls` versus using `heartbeat`.

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: the checkpoint SURVIVES release + reclaim so a different runtime can resume, and the call performs a full lease reset to the lease length from the moment it lands. The token-loss fallback (RTSC-758) and its exception are disclosed, none of which 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?

Front-loaded with the core action and the survival guarantee, and every sentence carries real information. It is dense with parentheticals and em-dash asides, so it reads as packed rather than crisp, but nothing is wasted.

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

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

With no output schema, the description carries the return-behavior burden and does so (checkpoint persists, lease resets). It does not state failure modes — e.g. what happens if the claim was lost entirely or the identifier is wrong — which would matter for a non-idempotent mutation.

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 meaningfully extends the claimToken parameter: omit only if lost, and a bare shared workspace key always requires it. `note` content structure is covered by the schema; `identifier` gets no elaboration beyond the required-field fact, which is the one 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?

States a specific verb and resource: record a handoff checkpoint on a claimed issue, with contents enumerated (done, next, gotchas, branch/artifacts). It also distinguishes itself from the sibling `heartbeat` by defining the relationship 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?

Gives an explicit selection rule: this is the PREFERRED call at any long-silence boundary because it does everything `heartbeat` does plus the note. It also states when to pass claimToken and the exception (bare shared workspace key always needs 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 this as destructive, non-read-only, idempotent, and closed-world, and the description adds substantial context: server-side binding to the acting human, one claim per source tool, refusal during imports, and billing-refusal behavior with tellHuman. That goes well beyond what annotations provide.

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

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

The purpose is front-loaded, followed by precise constraints and then error/billing behavior. Despite its length, each sentence carries operational value and there is no filler.

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

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

For a destructive claim operation with no output schema, the description covers the action, source of the id, identity binding, import refusal condition, and billing failure path. An agent has enough context to call it correctly and handle the main refusal modes.

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 already document the required memberId and name provenance. The description reinforces that memberId must come from the human’s explicit choice, but it does not add new syntax or format 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?

States a specific verb and resource: claiming an imported placeholder identity and absorbing its history. It clearly distinguishes this action from sibling tools like list_claimable_ghosts and dismiss_ghost_prompt by explaining the exact effect on the human account.

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 call it ONLY with an id the human chose from list_claimable_ghosts, never by inference, and never for anyone but that human. It also states the one-placeholder-per-source constraint and the refusal condition during a running import.

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 extensive behavior beyond the annotations: lease TTL dependent on proxy/no-proxy, renewal mechanics, sweep consequences, CLAIM_REQUIRED and AUTHOR_CANNOT_REVIEW errors, worktree isolation requirements, and billing refusal handling. 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 critical purpose and refusal conditions are front-loaded, but the description becomes a dense wall of operational detail with long parentheticals and all-caps warnings. Most content is relevant to correct use, but the extreme length and embedded lifecycle rules make it harder to scan 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 no output schema and a complex lease-based workflow, the description fills in every important behavior: return fields (`claim_token`, `branch`, `activeClaims`, `claimExpiresAt`, `rebound`, `renewedOnly`), renewal responsibilities by client type, failure codes, and required post-claim worktree setup.

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 would be 3, but the description adds meaningful semantics for `claimToken` beyond the schema: it resumes a prior lease onto a new session, is refused if the session never held the issue, and returns rebound/renewedOnly states. `identifier` is only lightly covered beyond the schema example.

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

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

The description opens with a specific verb and resource: 'Claim one specific issue by id.' It explicitly contrasts this with 'instead of letting next_issue pick,' making the tool's role distinct from the sibling that auto-selects work.

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 precisely when to use this tool versus next_issue and enumerates the refusal conditions (already held, blocked, work:false, invalid status). It also explicitly clarifies edge cases like claiming a `review` issue and resuming after a restart.

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 (write, idempotent, non-destructive), and the description goes further by disclosing that the dismissal is scoped to the current offer set and won't carry over to later sources. It also documents the billing-refusal path (BILLING_INACTIVE / MONTHLY_CAP_REACHED), the `tellHuman` field, and that an owner must resolve it — genuinely useful behavior 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?

Purpose is front-loaded, but the prose is padded with rhetorical emphasis ('PASS IT TO YOUR HUMAN', 'do NOT absorb the refusal') and repeats the 'answer on their behalf' idea. The billing content earns its place; the redundant exhortation does not.

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

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

For a zero-param write tool with no output schema, the description covers purpose, consent condition, persistence scope, and failure handling. It omits what a successful response looks like, which is the one 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?

The tool takes zero parameters, so there is nothing to document; baseline for 0-param tools is 4. The description does not waste space re-explaining absent inputs.

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 gives a concrete semantic action: record that none of the currently offered placeholders are the agent's human. This implicitly contrasts with the 'yes' path (claim_ghost / claim_issue), so an agent can differentiate it, though the jargon ('placeholders', 'ghost prompt') is obscure and only fully decodable from the tool name.

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 it only when they have said so — it is an answer on their behalf either way" gives an explicit when-to-call condition and a consent caveat. The scope clause about covering only currently offered source tools adds clear boundaries, but no sibling alternative is named by name.

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 adds valuable context the annotations cannot: the conditional return surface (filename/contentType/bytes only when `hasFile`). It stops short of saying what happens for an unknown id (error vs empty).

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, zero filler, and the key scoping word METADATA is capitalized and front-loaded before the sibling routing 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, the description correctly carries the return-value burden by listing the returned fields and their conditional availability. Only failure behavior (missing id, permission) is left unspecified for this small read 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?

Single parameter with 100% schema description coverage, so the schema already documents it as the attachment id. The description only echoes the 'by id' framing without adding format or lookup 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?

States a specific verb and resource ('Read one attachment's METADATA by id') and enumerates the exact fields returned, including the conditional ones guarded by `hasFile`. This is clearly distinguishable from the content-reading sibling.

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: 'To read the file's CONTENT, call get_attachment_file.' The alternative and the condition that selects it are named outright rather than 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 read-only/idempotent profile, but the description adds substantial context beyond them: no credential is needed (pre-empting a common agent failure mode), the exact size caps and why they exist (bytes travel through context), and per-type return shapes (image, text, base64). This is exactly the operational detail 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 with purpose and the no-credential warning, and every sentence carries a distinct fact (return types, size limits, proxy alternative, link attachments). It is on the long side — the credential warning and the size rationale could be tightened — but nothing is filler.

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

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

No output schema exists, and the description compensates by describing all three possible return shapes and their caps. With one required parameter, read-only annotations, and the sibling routing spelled out, an agent has everything needed to call this correctly or know when not to.

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

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

Schema coverage is 100% and the single parameter is documented as 'Attachment id.', so the schema already does the work. The description adds only implicit context — that the id refers to an issue attachment obtainable via list_attachments — without adding syntax or format detail. Baseline 3 is appropriate.

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

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

States a specific verb and resource — 'Read the CONTENT of a file attached to an issue' — and immediately distinguishes itself from metadata siblings by emphasizing CONTENT and 'ONE call'. An agent can tell it apart from get_attachment and save_attachment 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: check `bytes` on list_attachments/get_attachment first if size matters, switch to `retasc mcp-proxy` for files over the limit, and fetch the URL yourself for link attachments. Each alternative has a stated condition that selects 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 readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds real value by disclosing that returned data includes computed/derived surfaces (blocking status and the deadline fields), which the agent could not infer from annotations. It omits error behavior for missing issues.

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?

One sentence, front-loaded with the verb and scope, then a tight enumeration of returned surfaces. No filler, no repetition of the title.

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 correctly carries the return-value burden by naming the field groups an agent can expect, including computed ones. It could go further on the semantics of derived values (e.g. slaState values), but an agent has enough to select and 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?

There is a single required parameter with 100% schema description coverage and an inline example ("XEN-12"). The description adds nothing about identifier format or alternate forms, so the schema does all the work — the baseline 3 applies.

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

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

States a specific verb and resource ("Get one issue in full") and enumerates what 'full' means, which implicitly separates it from list_issues and next_issue. It does not explicitly name those siblings, so it stops short of a 5.

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

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

Usage is only implied: the field list suggests 'use this when you need complete detail on a single issue'. There is no explicit guidance on when to prefer list_issues or next_issue, or on what happens when the identifier doesn't resolve.

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, closed-world, so the description doesn't need to restate safety. It adds useful context the annotations don't cover: the payload includes an issue breakdown by status, and omitting the prefix resolves to the API key's own project.

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

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

Two short sentences, zero filler, and the highest-value fact (what the response contains) is front-loaded before the default behavior.

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 summarizing the returned content and the default argument resolution. For a one-parameter read tool, nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 100% and the single 'prefix' parameter is already documented with the same default note. The description's fallback sentence duplicates the schema rather than adding format or resolution details, so baseline 3 applies.

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

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

States a specific verb and resource ('Get a project') and adds that the response includes an issue breakdown by status, which is real information beyond the name. It implicitly contrasts with the sibling list_projects by being singular, but never names an alternative.

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: 'Get a project' vs. list_projects is inferable from plurality, and the default-to-own-project note hints at a common no-arg case. There is no explicit when-to-use statement or guidance on when to prefer list_projects or whoami.

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 contains useful behavioral detail, including the full lease reset, expiry durations, and `CLAIM_LOST` on expired leases. However, it says the lease is reset from the moment of each call, which conflicts with the annotation `idempotentHint: true`: repeated calls with the same arguments extend the lease further and therefore have an additional effect.

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 the core action and then adds the claim-token fallback, reset semantics, `checkpoint` preference, and expiry behavior. It is somewhat long for a heartbeat tool, but most sentences carry useful operational 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?

There is no output schema, but the description explains that the tool returns the new expiry. It also covers the key failure mode (`CLAIM_LOST`) and the lease-reset behavior, which is enough for an agent to call 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 50%, and the description thoroughly explains `claimToken`, including when to omit it and the identity exception. It does not explain `identifier` beyond implying it refers to a claimed issue, leaving one of two parameters under-specified.

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: extending a lease on a claimed issue during long-silent work. It also distinguishes the tool from its closest sibling by explicitly comparing it with `checkpoint`.

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 routing guidance: prefer `checkpoint` at long-silence boundaries, and use bare `heartbeat` only when there is nothing worth recording yet. It also states when to pass or omit `claimToken`, including the fallback and the shared-workspace-key exception.

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 a safe, idempotent read, so the lower bar applies—but the description clears it anyway. It discloses the crucial downstream consequence (a re-import reconciles onto the same issues and overwrites edits made since the last run) and the authorization requirement (owner or admin only), neither of which is visible in structured fields.

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

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

Three short sentences, front-loaded with the scope and then the actionable sequencing and warning. Every sentence adds a distinct, decision-relevant fact—no restatement of the name or title.

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 zero-param read tool with annotations carrying the safety profile, an agent has everything it needs: what it returns in broad terms (sources), when to call it, the risk it is meant to flag, and who can call it. No output schema exists, but the return content is adequately characterized.

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

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

The tool takes zero parameters, so the baseline of 4 applies and there is no parameter behavior a description needs to document. The description correctly spends no words on inputs.

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 in the first sentence: a read-only view of which sources this org has imported previously. That is more precise than the title and lets an agent tell it apart from run_import, but it never explicitly distinguishes itself from similar siblings such as list_import_sources, list_import_statuses, or latest_import.

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 ('Check it before running an import') and even prescribes an agent behavior (WARN your human if their source appears) along with the reason. It stops short of naming the sibling tools it is an alternative to, so the routing signal is implied rather than 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 only declare the generic profile (not read-only, open-world, non-idempotent, non-destructive); the description adds substantial context: authorization requires an active owner/admin principal, the code is returned once and stored only as a hash, the invite is a bearer token, expiry/revocation behavior, and that the caller gains no privileges. Strong disclosure, though the email-delivery and expiry details largely restate the 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-loads purpose and authorization, then walks through the two-pass call pattern in a logical order with the highest-stakes warning in caps. It is dense and long, and some sentences are redundant (the repeated 'never go hunting for an address' instruction) or add noise (the RTSC ticket references), which keeps it from 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 fully carries the burden: it explains what the no-argument call returns (the questions as data with exact options), what the final call returns (the raw code, once), the authorization preconditions, and the reversibility/expiry model. An agent has everything needed to invoke it correctly end to end.

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 explaining the intent behind choices the schema can't convey — that omitting `projectIds` is the safe default granting only this folder's project, why `allProjects` conflicts with it, and when `inviteeUserId` should be used. It doesn't enumerate formats or defaults beyond the schema, but the decision semantics are genuinely additive.

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 ('Invite a PERSON into your org') with explicit on-behalf-of scoping, and distinguishes it from siblings like list_invites, revoke_invite, and accept_invite by describing minting an invite code versus managing one. An agent can identify this as the creation/issuance step 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 explicit when-to-use rules ('NEVER call this unprompted — your human names the person'), a mandatory workflow ('CALL IT WITH NO ARGUMENTS FIRST'), and precise selection criteria between `projectIds`, omitting it, and `allProjects: true`. It even names the failure mode of combining the two. This is about as complete as usage guidance gets.

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

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

Goes beyond the read-only annotations by describing the returned information: status, issues done/total, summary, and failure reason. It also discloses concurrency behavior and permission requirements, which are important for correct invocation.

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 tightly written sentences with no wasted language. The core purpose and polling guidance are front-loaded, followed by the access constraint.

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 a zero-parameter, read-only tool with no output schema, the description supplies the missing output context, polling guidance, concurrency constraint, and permission requirement. An agent has everything needed 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?

The tool has no parameters, so there is nothing for the description to clarify beyond the schema. The baseline for zero-parameter tools is 4, and the description appropriately does not add unnecessary parameter details.

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: the most recent import in the org, including progress, outcome, summary, and failure reason. It distinguishes itself from import_history by focusing on the latest import and from run_import by framing itself as a polling tool.

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 poll this tool rather than starting another import, and notes that only one import runs per org at a time. It also states the owner-or-admin access restriction, giving clear when-to-use and prerequisite guidance.

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

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

Annotations already declare read-only, idempotent, closed-world behavior, so the bar is lower. The description adds genuine value beyond them: obsolete attachments are flagged rather than filtered out (so result counts include them), and hasFile distinguishes uploaded files from plain links.

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, zero filler, and the most decision-relevant fact (obsolete ones flagged, not hidden) is front-loaded before the field-level detail. Every clause 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?

No output schema exists, so the description usefully enumerates the returned fields (hasFile, bytes, contentType) and the obsolete flag. Only the input identifier's format is left unexplained, which keeps it short of 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 0%, so the schema documents nothing about the single required `issue` parameter. The description implies it is an issue identifier ("an issue's attachments") but never states whether it is a numeric ID, key, or slug — a notable gap for the only input.

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 an issue's attachments") and immediately disambiguates from get_attachment and get_attachment_file by framing this as the discovery step before fetching a file. An agent can distinguish it from the sibling fetch tools 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 clear usage context: call this first to see which attachments are readable and what pulling one will cost before calling get_attachment_file. It lacks an explicit when-not statement (e.g., use get_attachment for a single known ID), but the sequencing guidance is concrete.

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 corroborates with 'Read-only.' What it adds beyond the annotations is the consequence of a wrong downstream claim: permanent re-attribution of someone else's work that only an owner can unpick. It stops short of describing the response shape (name vs email fields), which is the one 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 definition, then the action imperative, then the warning, then the empty-list edge case — a sensible order with no filler. The all-caps directives are slightly heavy-handed but each sentence carries distinct 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 zero-param, output-schema-less list tool with full annotation coverage, the description supplies the missing pieces: what the entities represent, the empty-result case, and the mandated next action. Only the precise shape of a returned entry is 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?

Zero parameters, so there is nothing to disambiguate and the baseline of 4 applies. The description correctly frames the output as a list of names to be relayed verbatim, which is the only 'parameter-like' information an agent needs.

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 (imported placeholder identities in this org that could be the human) and adds defining properties: carried in by a migration, never signed in, history attributed to nobody. This clearly separates it from the action siblings claim_ghost and check_claim.

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 prescribes the next step (relay names verbatim and ask which one is them), explicitly forbids guessing and explains why, and states that an empty list means there is nothing to answer. Alternatives are named and the condition selecting them is clear.

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

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

Annotations already declare readOnly, idempotent, non-destructive, and closed-world behavior, so safety is covered. The description contributes the one genuinely new behavioral fact — comments are returned in chronological thread order — but says nothing about pagination, limits, or what happens for an issue with no comments.

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?

A single short sentence with the ordering constraint front-loaded and no filler. It is efficient, though arguably undersized for the semantic gaps it leaves unaddressed.

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 simple one-parameter read tool with rich annotations and no output schema, the description is close to sufficient, but the undocumented identifier format and absent return-shape or ordering-vs-pagination detail leave real gaps an agent could stumble on.

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 one required parameter at 0% schema description coverage, so the description must carry the semantics. It implies the parameter identifies an issue, but never states the expected format (numeric ID, key, or URL), which is precisely the information an agent needs to populate it correctly.

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 ('List') and resource ('an issue's comments') with an added ordering qualifier. It does not differentiate itself from adjacent read/list siblings such as list_attachments or get_issue, but the operation itself is unambiguous.

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

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

The description gives no explicit when-to-use or when-not-to-use guidance and never references the related write siblings (save_comment, retract_comment) or how to obtain the required issue identifier first. Usage must be inferred 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?

Goes well beyond the readOnlyHint/idempotentHint annotations by disclosing what is deliberately excluded from results: the inbound webhook secret and outbound GitHub token are NEVER returned. It also explains the security rationale (raw token must not transit MCP) and what hasToken actually signals about sync-back wiring, which 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?

Four tight sentences, front-loaded with the identity of the resource, then row shape, then the secret-exclusion guarantee. Every sentence carries operational meaning. Minor cost: internal shorthand ('Retasc', 'RTSC-189', 'Dash-only') adds noise for an agent without org context.

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

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

With zero parameters and no output schema, the description carries the full burden and does so: it covers identity, return fields, security exclusions, and the boundary against creating connectors. Nothing an agent needs to call this correctly 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?

Zero parameters yields the baseline 4. The description compensates usefully by enumerating the shape of each returned row (provider, repo, target project, hasToken, created/revoked timestamps), which is the only place that information exists since there is no output 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 ('List the org's intake connectors') and immediately grounds it with a concrete example ('GitHub Issues → Retasc issues'). It is clearly distinguishable from sibling list_* tools by naming the connector domain, and from revoke_connector by scoping itself to listing.

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 states when NOT to use this surface: 'Connecting a NEW repo is Dash-only' because it needs a raw GitHub token that must not transit MCP. It also frames scope as 'read + disconnect', implying revoke_connector for the disconnect half. It stops short of naming revoke_connector outright, so the routing is implied rather than 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 declare read-only, idempotent, non-destructive, closed-world, so the safety profile is covered. The description adds genuinely non-structured behavior: descriptors carry authFields and hint, secret-marked fields must be flagged as passing through the conversation and never echoed back. That credential-handling policy is a real addition 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?

Four tight sentences, with the inventory purpose front-loaded and procedural instructions after. Slightly dense with parentheticals and imperative asides, but no sentence is filler.

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

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

With no input params and no output schema, the description carries the burden of explaining the return shape and it does: authFields, hint, and secret flags. An agent has everything needed to call it and act on 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?

Zero parameters, so there is nothing to disambiguate; baseline is 4. The description instead characterizes the response payload's fields (authFields, hint, secret), which is useful orientation even though no input semantics are needed.

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

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

Names the resource precisely (import sources for Retasc: Linear, Jira, Asana, ClickUp, Shortcut) and states exactly what each descriptor returns, so the agent knows it is a static capability/inventory read. It is clearly distinguishable from siblings like list_import_targets, list_import_statuses, import_history, and run_import.

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 sequences itself: 'Start here before any other import tool,' which routes the agent ahead of run_import and the other import siblings. It also gives concrete downstream procedure (ask for authFields by label, use hint to guide the human), which no other tool covers.

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 and open-world, so the description is not obligated to repeat them. It instead adds genuinely new behavior: an 'Owner or admin only' authorization requirement, the empty-list case ('Returns [] for sources that do not support mapping'), and the incident rationale for why name-based inference was removed. It does not describe the item shape of the returned list, which is the 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?

The purpose is front-loaded, then the human-in-the-loop directive, then the anti-inference warning with its justification, then the edge case and permission note. Every sentence earns its place. The all-caps warning is loud and slightly bulky, but it is load-bearing given the described silent-failure incident.

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 three-parameter, fully documented read tool with rich annotations and no output schema, the description covers authorization, the empty-result case, and the required human interaction. It stops short only of describing the shape of each returned column entry, which an agent needs in order to pose the column-by-column question well.

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%: auth, source and targetRef are each documented, including provenance ('authFields from list_import_sources', 'id from list_import_targets'). The description adds no parameter-level meaning beyond what the schema already says, so the baseline 3 applies.

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

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

The description states the resource concretely: 'The chosen target's columns, so each one can be mapped to a Retasc status,' which tells an agent exactly what is returned and why. It implicitly distinguishes itself from list_import_sources and list_import_targets by referring to the chosen target. The only weakness is that the noun-phrase opening never names the verb 'list', and the tool name ('list_import_statuses') mismatches the title and body ('columns'), which creates a moment of ambiguity.

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 downstream procedure: relay the list to the human and ask column by column, and explicitly forbids inferring the mapping from column names. That is strong 'how and when' guidance tied to the import workflow. What is missing is an explicit sequencing statement (call after list_import_targets, before run_import) and any exclusion of alternatives.

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 openWorld, so the safety profile is covered. The description usefully adds that the credentials are used only for this call and never stored, plus the owner/admin permission gate — meaningful context beyond the annotations. It stops short of noting rate limits or failure modes of the external source call.

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 outcome and ending with the security reassurance. The clause 'so your human can choose which one to bring across' earns its place by explaining intent, though it is slightly chatty.

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 only two parameters, no output schema and full annotation coverage, the description is nearly complete: it covers purpose, prerequisites, and credential handling. The remaining gap is that it never sketches the shape of the returned targets (fields, pagination), which the agent must infer.

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 both parameters are documented structurally. The description's only added guidance is the provenance of the auth object ('the auth values you collected from them'), which the schema already states as authFields from list_import_sources; it adds no new syntax or format 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 (list) and resource (teams/projects/workspaces visible at the source given credentials), and frames its role in a larger flow. It is clearly distinct from sibling list_import_sources, which enumerates sources rather than targets within a source.

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?

Implies the correct sequence by telling the agent to pass 'the auth values you collected from them', pointing back to list_import_sources, and states a concrete prerequisite ('Owner or admin only'). It does not explicitly name what to do instead if the caller is not an owner/admin, nor call out a failure alternative.

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

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

Annotations already cover the safety profile (readOnly, idempotent, non-destructive), and the description adds genuinely new behavioral facts: the invite code is never returned, codes are stored only as hashes, `displayPrefix` is the distinguishing handle, and `mintedByAgent` reveals agent-vs-human minting. The authorization requirement (owner/admin via human principal) is also stated, which the annotations do not 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 with the resource and status scope, then the downstream use, then the caveats — good ordering with no filler sentences. The explanation of why codes are absent ('bearer tokens stored only as hashes') is slightly more rationale than an agent strictly needs, keeping it just under maximum.

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 return-value burden itself and does so: it names the status buckets and two key fields, plus the notable omission (invite code). Nothing an agent needs in order to call this correctly 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?

The tool takes zero parameters, so the baseline is 4; the description wisely spends its space explaining the returned fields (`displayPrefix`, `mintedByAgent`, status categories) instead of inventing parameter guidance.

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 ('Invites minted for your org') and enumerates the statuses covered (pending, accepted, revoked, expired), so the agent knows exactly what set is returned. It also distinguishes itself from `revoke_invite` by framing this as the read side that supplies the id the mutating sibling needs.

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 clear usage context — audit what is outstanding and obtain the id required by `revoke_invite` — and names the access prerequisite ('Owner or admin, through your human principal'). It stops short of stating when *not* to call it or how it differs from other listing tools such as `list_members`, so it is 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 cover the read-only/idempotent safety profile, but the description adds real behavioral context: the default exclusion of done/canceled, the priority-first ordering with None last and recent tiebreak, and the compact payload shape. Ordering and default filtering are exactly the traits an agent can't get from 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?

Front-loaded with purpose and payload summary, then defaults, then filtering/order, then the remediation pointer — a sensible priority order. Slight redundancy in stating slaState twice (parenthetical and final sentence) is the only 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?

With 7 optional params and no output schema, the description does the needed work: it sketches the returned fields, documents default scoping, ordering, and enum meanings for slaState. Only pagination behavior beyond the limit cap is left unaddressed, a minor 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?

At 86% schema description coverage, the schema already documents limit, author, assignee, status, priority, and the slaState thresholds. The description mostly restates the filter list ('status (one or many), priority, label, author, or SLA state') without adding syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb and resource ('List issues in the project') plus the scope of what is returned ('compact, each includes its author + createdAt + derived deadline slaState'). That payload summary cleanly separates it from get_issue/next_issue, which return single issues.

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 a concrete when-to-use case — 'poll slaState:"breaching" to find near-breach work for /loop remediation' — and states the default scope ('Defaults to active work (hides done/canceled)'). It does not explicitly name alternatives or exclusions versus sibling list/analytics tools, 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 readOnlyHint=true, idempotentHint=true, openWorldHint=false, and destructiveHint=false, so the safety profile is fully covered structurally. The description adds only the useful detail that results include issue counts, and says nothing about ordering or result size.

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?

One short sentence with zero waste; the scope and return content are front-loaded.

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 no-parameter, read-only list tool with full annotation coverage and no output schema, the description conveys scope and roughly what comes back. Minor gaps (ordering, whether all labels or a capped set) remain undisclosed.

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?

Zero parameters, so the 4 baseline applies; there is nothing for the description to compensate for. The schema is trivially complete.

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 (List) and resource (labels) plus scope (in the org) and even an extra attribute (issue counts). It does not differentiate itself from save_label, the obvious write counterpart, but the operation 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?

No guidance on when to call this versus alternatives, no prerequisites, no note that save_label is the mutation counterpart. An agent can infer 'listing labels' but nothing in the text routes 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?

The description discloses critical behavioral traits beyond the annotations, namely the types of status values (`active`, `suspended` for persons, `retired` for agents) and the persistence of these statuses for historical attribution. This prevents the agent from making incorrect assumptions about the data state.

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 definition is efficiently structured. It front-loads the core concept and uses the second sentence to deliver a dense, essential piece of business logic regarding status, making every sentence contribute meaningful context.

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 that the tool is simple (1 parameter, no output schema), the description is exceptionally complete. It covers the entity types, the filtering mechanism, and the vital status definitions, ensuring the agent has all necessary context.

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 input schema coverage is 100%, so the primary parameter is adequately documented by the schema itself. The description simply repeats the option to filter by name, adding no semantic value beyond what the structured data provides. Baseline score 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 clearly identifies the purpose as listing members, explicitly distinguishing between 'humans' and 'agents.' This prevents ambiguity for the AI agent when choosing the correct roster-based tool.

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?

While it does not name a competing sibling tool, it provides clear guidelines on how to use the data responsibly, specifically advising the agent to check the `status` before assuming a member is active. This is crucial for correct operational workflow.

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. The description adds the org-wide scope and the tuple of returned fields, but says nothing about ordering, pagination, or whether archived projects are included.

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?

A single short sentence with zero filler, and the scope and resource are front-loaded. Nothing could be removed 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 trivial zero-parameter list tool this is close to adequate, and the mention of returned fields partially compensates for the absent output schema. Still missing: ordering, pagination/result-size limits, and whether the listing is filtered or complete — details that matter when an agent decides how to consume 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?

The tool takes zero parameters, so there is nothing to disambiguate; baseline 4 applies. The parenthetical field list describes output shape rather than inputs, which is fine but not a parameter contribution.

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 projects") plus the scope ("in the org") and the fields returned. It is clearly distinct from the singular sibling get_project, though it never names that sibling explicitly.

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

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

Usage is only implied by the verb: an agent can infer this is the browse-all-projects entry point before drilling into get_project. There is no explicit when-to-use guidance, no exclusion, and no mention of how it relates to get_project or list_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 already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond them: which rows are silently filtered out (imported placeholders), why that filter exists (a parked review strands gated work), and the owner/admin authorization requirement.

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 core question ('who can be named as the reviewer') and ending with the access constraint. The placeholder rationale is slightly verbose but directly justifies a surprising filtering behavior, so it mostly 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 zero-parameter read with strong annotations and no output schema, the description covers eligibility scope, the empty-result case, and authorization. It leaves the shape of each returned candidate unstated, which is a minor gap given no output schema exists to document 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the empty-object schema is self-explanatory. Baseline of 4 applies with no gaps to compensate for.

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 (reviewer candidates eligible to sign in and claim) and frames it around the concrete task of mapping a column to `review`. It implicitly differentiates from list_members by emphasizing that imported placeholders are excluded, though it never names that sibling explicitly.

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

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

It says exactly when to use it (when mapping a column to `review`), what to do on an empty result ('say so and map that column to something else'), and who may call it ('Owner or admin only'). No inference is required from 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?

Discloses behavior beyond the annotations: the raw key is returned exactly ONCE, the minted credential has the same access as the caller's key with no privilege change, and a harness retired in this workspace is refused. This is consistent with idempotentHint=false and destructiveHint=false without restating them.

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

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

Front-loads the core action and hierarchy, then layers rationale and constraints. Slightly long and repeats the 'no privilege change' idea twice, but nearly every sentence carries operational weight.

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?

Covers what annotations and schema cannot: credential lifetime (returned once), refusal cases (retired harness, unplaceable name), authorization scope (workspace keys only), and the caller's caching pattern. No output schema exists, and the return-value behavior is explained anyway.

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 the harness id format and the refusal-on-unplaceable-name rule in detail. The description's only addition is provenance — the id comes from the initialize handshake — so the baseline of 3 is appropriate.

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

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

States a specific verb and resource ('Mint the API key for ONE TOOL in this workspace') and precisely places it in a three-tier key hierarchy, distinguishing it from mint_session_key and the folder's workspace key. An agent can tell immediately what it creates and at which level.

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

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

Names the caller and the moment of use explicitly: 'The watchdog proxy calls this once it knows which harness is on the other end (the initialize handshake names it)'. It also gives the constraint 'Workspace keys only' and explains the alternative design cost (shared .mcp.json blocking independent retirement) that justifies using this 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?

Beyond the annotations, the description discloses critical behaviors: the raw key is returned ONCE, the session key has the same access as the caller's key (no privilege change), and billing refusals (BILLING_INACTIVE or MONTHLY_CAP_REACHED) carry a tellHuman sentence that must be relayed to a human. These details are essential for correct handling of the tool's output and failure modes.

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 the core purpose and then flows into proxy usage, key return behavior, and billing refusal instructions. Every sentence adds value, though the capitalized 'PASS IT TO YOUR HUMAN' is slightly emphatic but justified for urgent instruction. It is appropriately sized for a proxy-only tool with nuanced failure modes.

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?

The description covers the tool's identity binding, proxy usage context, one-time key return, access level, and billing failure handling. With no output schema, the mention of the response's tellHuman field provides sufficient return value information. It does not explicitly address the optional parameters beyond labeling, but the schema covers those completely.

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

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

Schema description coverage is 100%, so the input schema already documents all three parameters in detail. The description adds only a hint about labeling ('distinctly labeled') but does not explain the autoUpdate or cliVersion parameters. With the schema doing the heavy lifting, a baseline score of 3 is appropriate.

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

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

The description specifies the exact action and resource: 'Mint a per-session API key bound to YOUR identity (same org/project/agent)'. It also clarifies this is proxy-only and used at startup. However, it does not explicitly differentiate from the sibling tool mint_harness_key, which could cause confusion for an agent choosing between key-minting 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?

It states when to use this tool: 'The watchdog proxy calls this once at startup and uses the returned key'. It also provides a strong when-not: 'do NOT absorb the refusal and continue with read-only work as if the session were healthy'. But it does not mention alternatives like mint_harness_key, leaving a gap in sibling selection guidance.

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

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

Annotations establish that this is a non-destructive, idempotent, non-open-world write operation. The description adds useful behavioral context beyond annotations: automatic CLI invocation points, workspace-key-only scope, and the fact that Retasc never stores paths. It does not cover error behavior or permissions, so it is strong but not exhaustive.

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

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

The purpose is front-loaded in the first sentence, followed by invocation context and constraints. The parenthetical listing of CLI call sites is somewhat long but still useful for preventing misuse.

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 mutation with annotations and full schema coverage, the description covers purpose, scope, caller context, and a key privacy constraint. It does not describe response behavior, but no output schema exists and the operation is simple enough that this is a minor 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 the schema already says the parameter is the folder's own name, not a path. The description reinforces this and adds the rationale that Retasc never stores paths, which adds meaning beyond the schema even though it does not introduce new syntax.

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: telling Retasc which folder a workspace key is bound to so the Dash can report where an agent runs. It also scopes the operation to workspace keys and clarifies that the value is the folder's own name, not a path.

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

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

It gives clear usage context: the CLI calls this automatically at bind, session start, and setup, and an agent has no folder of its own to report. This effectively communicates when the tool is not agent-initiated, though it does not name an alternative sibling tool or say explicitly what an agent should do 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?

Goes far beyond the annotations: discloses lease TTLs (30 min behind proxy, 2 h without), exactly which calls renew it, the worktree-per-issue isolation requirement with rationale, dependency-setup gotcha on fresh worktrees, and billing-refusal behavior. The annotations only say readOnly=false / not idempotent; the description supplies the entire operational contract.

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 is well front-loaded, but the body balloons into several hundred words of lease renewal policy, session-id echo rules, proxy watchdog behavior, and billing refusal handling that apply across many tools, not just this one. The actionable call-shape content (peek vs claim, lane scope, worktree) is buried and an agent must wade through renewal minutiae to reach 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?

With no output schema, the description still names the full response shape ({issues, ready, otherLanes, blocked, claimed}) plus per-issue branch and claim_token. Combined with the empty-wave and billing-refusal paths, an agent has everything needed to call this 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 100% with each of the three params already documented (n default 5/max 25, claim default false, allLanes default false). The description restates those defaults rather than adding format or edge-case meaning beyond them, so the baseline 3 applies. It does add that each claimed issue carries a claim_token and branch, but that is about return values, not parameter semantics.

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

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

The opening sentence states a specific verb+resource+scope: return the top N eligible issues (todo + unclaimed + unblocked WORK), priority-ordered, parallel-safe. It even defines 'eligible' inline. It stops short of naming the obvious siblings (next_issue, claim_issue, list_issues) that an agent must distinguish this batch tool from.

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

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

Clear mode-selection guidance: default peeks for planning, claim:true atomically claims, allLanes:true widens scope, and empty-wave-plus-otherLanes has an explicit prescribed action (relay tellHuman). What is missing is explicit routing against alternatives — nothing says when to prefer next_issue or list_issues over this.

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 this is a non-read-only, non-idempotent mutation, and the description adds substantial behavioral context beyond that: atomic claiming, lease TTLs, renewal rules, exhaustion response shapes, billing refusal behavior, and lane scoping. Nothing contradicts the annotations, and the added detail is unusually rich.

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 the description is extremely long and dense, with extensive operational guidance about worktrees, dependency setup, lease renewal modes, proxy behavior, session IDs, and billing errors. Much of that material is useful, but the overall size and repetition make it harder to scan than it needs to 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?

Given the complexity of atomic claiming, lane scoping, lease renewal, and no output schema, the description is complete enough to call the tool correctly. It describes the success path, empty-result diagnostics, claim_token, branch, activeClaims, claimExpiresAt, and tellHuman behavior.

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% for the sole allLanes parameter, so the baseline is 3. The description adds real semantic value by explaining the default lane-scoped behavior, the meaning of opting into allLanes, and the policy that the agent should not cross lanes on its own.

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 gives a specific verb and resource: atomically claim the highest-priority unblocked issue and return it with a claim_token. It also distinguishes this from siblings like next_batch, claim_issue, heartbeat, and checkpoint, so an agent can identify the tool's role 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?

The description explicitly covers when to use next_issue, when to opt into allLanes, and when to use next_batch for concurrent batch work. It also routes the agent to heartbeat/checkpoint/release/check_claim for lease management, leaving little ambiguity about alternatives.

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 disclosing the soft-delete retention behavior, the reason requirement, and a specific partial-failure mode — billing refusals returning a `tellHuman` relay sentence that the agent must surface rather than absorb. That is exactly the kind of operational 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-loads the operation and its semantics in one clause, then devotes the remainder to the billing failure path. Slightly long and the all-caps emphasis is heavy-handed, but every sentence carries actionable 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?

No output schema exists, yet the description covers the one response condition an agent must handle (billing refusal with `tellHuman`) and explains why continuing read-only work is not a valid fallback. Complete for a two-parameter mutation with strong annotation coverage.

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%; `attachment` is self-documented and `reason` is bare. The description adds only that the reason is required (already in the schema's required list) and says nothing about expected reason content, length, or format. Baseline 3 fits a two-parameter tool where the schema does most of the work.

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 immediately disambiguates semantics with 'the delete-equivalent — keeps it as a record,' which separates it from a hard delete and from the read-oriented siblings like get_attachment and list_attachments. An agent knows exactly what state change this performs.

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?

Makes the use case explicit (retire an attachment without destroying the record) and states that a reason is mandatory, plus detailed guidance on what to do when the call is refused for billing. It stops short of naming a sibling alternative or stating when this is preferable to leaving the attachment active.

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 is consistent with that (it only mints a URL; the caller does the POST). The description adds real behavioral context — the auth requirement (agent API key, not a CLI session token), the returned uploadUrl, query params for filename/title, and the response shape. But part of the credit is for repeating the auth/flow that the tool's own name and annotations partly imply, so it lands above baseline but not at the top.

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 routing recommendation ('PREFER save_attachment_file'), which is the most decision-relevant info. The curl example and the 'if you are a model' note are useful but add length; still, most sentences earn their place via concrete flow 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?

With no output schema, the description supplies the return shape ({uploadUrl} and the example POST response with id/url) and the full invocation flow. Combined with the routing alternatives, an agent has everything needed to decide whether and how to call 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 description coverage is 100% and the single `issue` parameter is fully documented in the schema, so the baseline is 3. The description mentions 'an issue's file attachments' but adds no format or constraint details beyond what the schema already provides.

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 the raw upload endpoint for an issue's file attachments') and immediately distinguishes itself from sibling tools save_attachment_file and save_attachment. An agent can tell exactly what this returns and how it differs from the one-call 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?

Explicitly says PREFER save_attachment_file, gives the condition for using this tool instead (human or script holding an agent API key), and routes plain-link use cases to save_attachment. When-to-use, when-not-to-use, and alternatives are all stated.

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

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

Annotations already establish readOnly, idempotent, non-destructive, closed-world behavior, so the safety profile is covered. Beyond that, the description adds genuine domain semantics: SLA counts are scoped to non-terminal issues, dependency blocks identify the blocking item, and a stale lastRenewedAt is interpreted as an unresewed claim running on bare TTL.

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 verb-and-object, then a tight enumeration; every clause carries information. The nested parentheticals (especially the claim/lease explanation) make it dense, but no sentence is padding.

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 must itself convey what comes back, and it does: status counts, ready-to-pull totals, breaching/breached counts, dependency-blocked detail, and claimant/lease fields. An agent knows what to expect from the response without a schema.

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

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

The tool takes zero parameters (100% schema coverage on an empty object), so per the rubric the baseline is 4. There is nothing further for the description to clarify about inputs.

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 — 'Diagnose the queue' — then enumerates the exact facets it reports (counts, ready-to-pull, SLA pressure, dependency blocks, active claims). This distinguishes it from siblings like list_issues, next_batch, and check_claim, which cover narrower slices of the same domain.

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

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

Usage is implied: this is the broad diagnostic overview, so an agent can infer it is the right call before drilling into check_claim or list_issues. However, the description never explicitly says when to prefer it over those siblings, nor when not to use it, so the routing decision 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 readOnlyHint=false, idempotentHint=true, and destructiveHint=false, but the description still adds substantive non-annotation context: what state is restored (org visibility plus prior role), which subject types are rejected, and the permission ceiling for admins. The one gap is failure/error behavior when an admin attempts a suspended owner/admin, which is implied but not spelled out.

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 effect, then constraints, then the parameter source — no filler sentences. It is dense to the point of being slightly hard to scan due to heavy capitalization and stacked em-dash clauses, but nothing is redundant enough to cut.

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 only one parameter, the description covers what an agent needs: what changes, who is allowed, who is rejected, and where the id comes from. Return value shape is unspecified, but the annotations carry idempotency and safety, so the remaining gap is minor.

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

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

Schema coverage is 100% and the single parameter is documented, so the baseline is 3. The description earns one step above baseline by disambiguating the id as a PERSON member id (not an agent id) and widening the provenance hint to list_members/whoami, which the schema alone only partially states.

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 (reactivate) and resource (a suspended PERSON), plus the concrete effect: restores org visibility and prior role. It explicitly carves out the AGENT case as impossible, which no sibling name or schema conveys, so an agent can distinguish this from retire_member, suspend_member, and invite_member at a glance.

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 the positive trigger (a suspended PERSON), the exclusion (an AGENT, since retire is terminal and nothing remains to reactivate), and the authorization rule (through the human principal; an admin may reactivate ordinary members only, never a suspended owner or admin). It also routes to list_members/whoami to obtain the id, so no inference is needed to decide whether this tool applies.

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 writes (readOnlyHint=false), is idempotent and non-destructive; the description adds genuinely new behavior: it stores the NAME of the transcript, never its contents (a privacy/data-scope guarantee), and that model/subagent status is recorded only when the harness reports it. It does not cover error behavior (e.g., what happens with a non-session key), which keeps this short of a 5.

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

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

The core action is in the first clause, caller/skip guidance follows, and the storage-scope caveat is compressed into one short sentence. Three dense sentences with no restated title or filler.

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

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

For a 6-parameter write tool with no output schema, it covers action, caller, precondition, what is and is not persisted, and the optionality of secondary fields — enough for an agent to call it correctly without further context.

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 still adds useful semantics by framing model and agentType as conditional facts the harness may never supply ('when the harness reports them'), discouraging an agent from fabricating them. It does not add format or syntax detail for transcriptId or harness beyond what the schema already states.

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 ('Record this harness session's transcript id on YOUR session key') and immediately names the consumer benefit (Dash conversation view, `claude --resume <id>`). It is clearly distinguishable from nearby siblings like mint_session_key or heartbeat, since those mint or ping a key while this attaches a transcript id to an existing one.

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 who calls it and when: the watchdog proxy does it automatically via SessionStart/GROK_SESSION_ID, and 'an agent only needs it when running without the proxy.' It also states the hard prerequisite 'Session keys only,' giving an agent both the trigger and the precondition for use.

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, which only say non-readonly, idempotent, non-destructive. The description discloses that comments and the checkpoint persist so the next agent resumes, that the omit-token path is authenticated by session identity, and the precise exception where that fallback fails — exactly the operational facts an agent needs before a 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?

Four front-loaded sentences that open with the state transition and then handle the token fallback and the note semantics. Every sentence carries information, though the parenthetical '(crash, dropped field, a context summary)?' is slightly chatty.

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 3-parameter mutation with no output schema, the description covers what changes, what survives, how authorization degrades, and what the optional note should contain. Nothing an agent needs to invoke 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?

Schema coverage is 67%, so the baseline is 3. The description genuinely enriches claimToken (the session-recognition fallback and the shared-key exception are not in the schema) and explains what note should contain, but it never mentions the required `identifier` parameter, which is undocumented in both places.

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 with the resulting state transition: 'Give a claimed issue back to the queue (reverts to todo).' The explicit outcome ('reverts to todo') makes it unmistakable against siblings like claim_issue, checkpoint, or save_issue.

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 clear conditional guidance on the claimToken: pass it when held, omit it when lost, and never omit it under a shared workspace key with no per-session key. It stops short of naming sibling alternatives (e.g. checkpoint for a mid-work save vs. release for handoff), so usage context is strong but not fully routed.

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, so the safety profile is covered. The description adds genuinely non-redundant behavior: the BILLING_INACTIVE / MONTHLY_CAP_REACHED refusal mode, the `tellHuman` field, and the warning that all value-bearing writes keep failing until an owner acts. It omits reversibility and what happens when the link doesn't exist.

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

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

Purpose is front-loaded in the first clause, followed by the failure-mode guidance. The billing passage is long but each sentence adds an actionable instruction (relay to human, do not absorb, do not continue read-only). No filler.

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

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

Strong on the failure path despite having no output schema, which is the hardest part for a destructive mutation tool. However, an agent is left without guidance on parameter direction/type semantics and on the success or missing-link behavior, which matters for a destructive, idempotent unlink.

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 0%, so the description must carry the burden — and it does not. Nothing explains sourceId vs targetId, and nothing explains the `type` enum (blocks / blocked_by / related / duplicate), whose directionality is exactly what an agent would get wrong when unlinking. 'Same args as add_relation' is a pointer, not a semantic explanation.

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 — 'Remove a link between two issues' — and anchors it against the sibling add_relation, so it is distinguishable from the create-side tool. Slightly short of 5 because the 'same args as add_relation' framing offloads the resource semantics onto another tool rather than stating the entity being unlinked (source vs target issue).

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 a clear conditional protocol for the billing-refusal path: pass `tellHuman` to the human and do not silently fall back to read-only work. That is real when-to-use/when-not guidance. It does not explicitly state the mirror-image relationship ('use add_relation to create, this to unlink') or prerequisites, so it stops short of 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 annotations: each reported worktree creates a provisional hold, the hold is visible as `hold`, automatic dispatch withholds it, it is not a lease, lacks a token, expires after 60 minutes, and an explicit claim converts it. These details align with the annotations rather than contradicting them.

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 critical machine-tool/proxy-only framing, then uses the remaining sentences for necessary hold semantics. The length is justified by the complexity of the side effects and lifecycle.

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?

Covers caller, scope, side effects, hold lifecycle, dispatch behavior, claim interaction, and exclusions. With no output schema, this is enough for an agent to understand why it should not call the tool and what would happen if it did.

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 field-level meaning is already documented. The description still adds useful input semantics by specifying that only unclaimed `rtsc-NN/<slug>` worktrees should be reported and by listing what is ignored: already claimed, terminal, `work:false`, or out-of-project items.

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 (report git worktrees) and immediately identifies the caller as the mcp-proxy rather than an agent. This clearly distinguishes it from agent-facing sibling tools like claim_issue and next_issue.

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 the proxy calls this on its own and an agent never needs to, which is a clear when/when-not instruction. It also explains interactions with claim_issue, next_issue, next_batch, and check_claim, leaving little ambiguity.

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 the annotations' destructiveHint/idempotentHint, it discloses irreversibility ("a revoked key can't be un-revoked", "no reactivate"), what happens to the underlying row (hidden for attribution vs. hard-deleted for a never-authenticated stray), and the authorization model (agent carries principal's authority; admin refused an owner's or peer admin's agent). That is substantive 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 with the core action and its consequences, with sibling routing placed before the authorization nuance. It is dense — multiple parentheticals and stacked clauses — so it is slightly harder to scan than ideal, but nearly every clause carries distinct 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 single-parameter destructive mutation with no output schema, the description covers effects, reversibility, data-retention outcomes, authorization preconditions, and the error mode for cross-org ids. Nothing an agent needs before calling 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 source and failure semantics: memberId comes from list_members/whoami and a member from another org yields NOT_FOUND. It does not add value-format detail, so it stops short of 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 ("Retire an AGENT — the terminal offboard") and immediately enumerates the concrete effects: revokes keys, releases claim, removes from roster. It also explicitly distinguishes the resource class (agent vs. person) from the sibling suspend_member.

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

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

Gives explicit when-to-use (terminal offboard, owner or admin), names the alternative for the other case ("For a PERSON use suspend_member instead"), and states the exclusion (retiring a human is rejected). This is a complete routing rule.

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, and the description adds meaningful context beyond them: the text is preserved as struck-through memory and the note is shown un-struck. It also discloses the BILLING_INACTIVE / MONTHLY_CAP_REACHED refusal behavior and the tellHuman field, which the annotations could never 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 core purpose and alternative are front-loaded in the first sentence, and every section carries operational value. The billing-refusal paragraph is somewhat long and emphatic, but it earns its place by preventing a costly agent mistake.

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 compensates by explaining the response's tellHuman field in the failure case. For a two-parameter mutation with annotations covering safety, this is complete enough to call 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 the baseline is 3, but the description adds real meaning: it explains that the note is displayed un-struck and that the comment id comes from list_comments. This goes beyond the schema and helps an agent supply correct values.

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

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

The description opens with a specific verb and resource ('Retract a comment') and immediately clarifies the semantics ('strike it through instead of deleting — the text stays as memory'), which distinguishes it from a delete operation. An agent knows exactly what this tool does without opening the schema.

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

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

It explicitly contrasts with deletion and states the prerequisite of a note explaining why the comment is no longer valid, plus detailed guidance on handling billing refusals. It stops short of naming a sibling tool as the alternative path, but the when-to-use context is clear.

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

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

Goes well past the annotations (destructiveHint/idempotentHint are already declared) by disclosing concrete consequences: inbound webhook stops syncing, the endpoint returns 401, the row persists but is flagged, and an unknown or other-org id yields NOT_FOUND. It also makes clear the action cannot be undone via this 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?

One dense but front-loaded passage: verb and resource first, then side effects, then the alternative path. No filler sentences and no repetition of annotation data as prose.

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

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

For a single-param mutation with no output schema, everything an agent needs is present: id source, side effects, idempotency, tenancy scoping, failure mode, and how to reverse the action.

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 repeats the 'from list_connectors' hint, so baseline is 3; the description earns a bump by specifying what an invalid id means ('an unknown/other-org id is NOT_FOUND'), which adds validation and scoping semantics the schema does not carry.

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 ('Disconnect an intake connector by id') and immediately clarifies the mechanism: marking revoked so the webhook stops. It is clearly distinguished from list_connectors (the id source) and from any delete semantics via 'Revoke-don't-delete'.

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?

Tells the agent where the id comes from (list_connectors), that the operation is idempotent and org-scoped, and explicitly routes the reverse operation elsewhere: 'To reconnect, use the Dash'. The revoke-instead-of-delete framing acts as an implicit when-not-to-use for destructive removal.

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 the annotations' destructive/idempotent hints, it discloses refusal semantics for accepted invites, NOT_FOUND for cross-org ids, the no-op-on-repeat behavior, and the permission model. These are exactly the failure modes an agent needs before firing a destructive call.

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 constraint (fires before use, undo for invite_member) is front-loaded and every clause carries information. Minor deduction for the embedded ticket reference '(RTSC-729)', which is noise for an agent, and for packing multiple constraints into one long sentence chain.

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-param destructive tool with no output schema, it covers the permission requirement, error cases, and idempotency, which is most of what a caller needs. It does not describe what a successful call returns, leaving the agent to infer the success shape.

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

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

Schema coverage is 100% and the single `inviteId` is already documented as coming from list_invites, so the description's provenance note largely restates the schema. Baseline 3 applies because the schema does the heavy lifting here.

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 up front ('Kill an invite before anyone uses it') and frames it relationally as 'the undo for invite_member', which immediately separates it from the other invite/member siblings. It also names the adjacent tools it is not (suspend_member) and the tool that feeds it (list_invites).

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 ('a mis-sent invite'), an explicit when-not ('an ALREADY-ACCEPTED invite is refused'), and the correct alternative in that case (suspend_member removes the person instead). The authorization precondition ('Owner or admin, through your human principal') is stated rather than left to discovery.

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=false, but the description adds the concrete consequences: it writes real issues, it cannot be undone, a wrong statusMap silently moves live work out of dispatch, the server refuses a missing or empty map, and access is owner/admin only. It also documents the billing refusal path (BILLING_INACTIVE / MONTHLY_CAP_REACHED) and the `tellHuman` relay contract, none of which is recoverable 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 purpose and the irreversibility warning, and essentially every clause carries operational consequence. It is a single dense block of run-on sentences, though; the destination and statusMap rules would land faster as discrete lines given the volume of high-stakes instruction.

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?

Covers prerequisites, irreversible effects, permission requirements, and the failure/escalation path — strong for a 6-parameter destructive tool with no output schema. The one gap is the success path: it never says what a completed call yields or references latest_import / list_import_statuses for tracking the import.

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 bar is baseline 3, but the description meaningfully deepens `destination` (which value produces a project invisible from this context) and `statusMap` (maps EVERY source column id, must be the human's actual answer, refused if empty, silent dispatch breakage if wrong). `reviewerByStatus` is tied to the review-mapped columns, giving an agent the conditional relationship the schema alone doesn't state.

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 ('bring a backlog across') and enumerates the exact source systems Linear, Jira, Asana, ClickUp, Shortcut. That separates it cleanly from the surrounding import siblings (list_import_sources, list_import_targets, import_history, latest_import), which are discovery/polling calls rather than the mutation itself.

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 gating: confirm with your human first, relay the re-import warning if import_history showed this source before, offer `this_project` first when the bound project is empty versus both options when it already has work. It also names the condition under which a refusal should escalate rather than be absorbed, which is the kind of when/when-not guidance most definitions omit.

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: it names the exact failure codes (BILLING_INACTIVE, MONTHLY_CAP_REACHED) and the `tellHuman` response field, and instructs the agent not to silently degrade. It omits success-path behavior, such as what is returned or whether re-attaching the same URL creates duplicates (annotations mark idempotentHint=false but the description never addresses that).

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

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

The purpose is front-loaded in the first clause, and the billing warning, while emphatic and long, carries actionable instructions that would otherwise be lost. Some of the capitalized admonishment could be trimmed 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 mutation tool with no output schema and low parameter coverage, the description handles the failure mode thoroughly but leaves gaps: no success return shape, no parameter meanings, no mention of non-idempotency despite the annotation.

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% and the description adds no meaning to any of the three parameters. Notably `title` is optional and unexplained — an agent cannot tell whether it labels the link or overrides something else — and `url` has no format or validation guidance.

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 ('Attach a link (URL) to an issue'), which naturally separates it from save_attachment_file and prepare_attachment_upload. It does not explicitly name those siblings, so it falls just 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 strong guidance for one narrow scenario — what to do when the call is refused for billing — but says nothing about when to choose this tool over save_attachment_file or prepare_attachment_upload, nor any prerequisites like issue permissions.

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 say it is a non-read-only, non-destructive, non-idempotent write. The description adds the hard 262144-byte decoded limit and the reason for it, the credential story (proxy holds it; no API key needed here), and the billing-refusal semantics (BILLING_INACTIVE / MONTHLY_CAP_REACHED, `tellHuman`, don't silently continue). That is substantive 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-loads the action and the size limit, then alternatives, then the failure path — good ordering with no wasted preamble. The closing billing paragraph runs long relative to a single tool call, though the content is useful.

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 4-param write tool with no output schema, it covers the size ceiling, encoding format, alternative paths, credential handling, and the exact error-code behavior to expect. Nothing an agent needs to invoke 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?

Schema coverage is 100%, so `issue`, `filename`, `title`, and `contentBase64` are already documented. The description only reinforces the base64 encoding and size ceiling; its mention of a `path` parameter refers to the proxy variant and is not a property of this schema, which could mislead. Baseline 3 fits.

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+mechanism: attach a file to an issue via base64 in one call. It explicitly separates itself from the two nearest siblings, save_attachment (links) and the proxy `path` variant, so an agent can distinguish it without reading schemas.

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

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

Gives explicit routing rules: use this for base64 under 256KB, use `retasc mcp-proxy` with `path` for larger files, use save_attachment for a plain link instead. It also pre-empts a failure mode (don't go reading credential 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?

Goes far beyond the annotations by documenting a concrete failure mode (BILLING_INACTIVE, MONTHLY_CAP_REACHED), the response field to expect (tellHuman), and the correct agent behavior (relay to human, don't silently continue read-only). This is exactly the behavioral 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?

Purpose is front-loaded in one short sentence, then the billing paragraph. The billing block is long but earns its place by changing agent behavior; a slight trim of the emphatic repetition would improve 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?

For a 2-param write tool with no output schema, the description covers purpose, usage motivation, and the critical error path with the exact field name returned. Only missing pieces are body content expectations and confirmation of what a success response looks like.

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%: `issue` is documented inline, `body` is not. The description's guidance to 'record what you did and why' gives soft content guidance for body, but no format/length constraints. Baseline 3 given partial schema coverage.

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 to an issue.' Unambiguous about what the tool creates, though it never explicitly distinguishes itself from siblings like list_comments or retract_comment.

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

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

The 'comments + activity are shared memory — record what you did and why' line implies the intended usage pattern, but there is no explicit when-to-use/when-not guidance and no named alternative for reading or deleting comments (list_comments, retract_comment exist as siblings).

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 say write/destructive/non-idempotent; the description adds the rejection gates (four required create declarations, `DUPLICATE_CHECK_REQUIRED`), the `labels` replace-not-merge side effect, and the billing-refusal handling via `tellHuman`. It loses a point because a large share of this content is restated in the schema field descriptions rather than being net-new behavioral context.

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

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

The create/update split is front-loaded and the required-declarations list is well enumerated, but the prose is bloated with editorial asides ('the cheapest issue to file is the one you don't file twice', the 2026-08-25 anecdote, the billing admonition) and repeats `reviewedSimilar` logic already in the schema.

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 15-parameter, zero-annotation-coverage-of-gates, output-schema-less mutation tool, it covers required-on-create fields, state-transition constraints, and error recovery. It stops short of stating update merge semantics (which omitted fields are left untouched) or what a successful write returns.

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 each of the 15 parameters is already documented exhaustively in the schema, so the baseline is 3. The description adds cross-parameter rules (which fields are required together on create, that `handoff` is valid only on the review entry) but repeats most field semantics verbatim.

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 precise verb+resource pair and immediately splits the two modes: create when `identifier` is omitted, update when it is passed. It is unmistakably distinct from siblings like save_comment, add_relation, and claim_issue.

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 names the alternative path (search with `list_issues` first) and the decision rule when a look-alike exists ('if one of them IS this work, do not create — comment on it or claim it'). It also states when not to send `reviewedSimilar` (no look-alikes) and how to recover from a refusal.

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 idempotency and non-destructiveness, so that part repeats what is already declared. The description still adds real value beyond the annotations: it documents the BILLING_INACTIVE and MONTHLY_CAP_REACHED refusal modes, the tellHuman response field, and the fact that only an owner can fix the billing problem. That failure-mode disclosure is the kind of behavioral context an 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?

The purpose is front-loaded in the first clause, which is good, but the majority of the text is a long billing-failure lecture with emphasis formatting. The content is genuinely useful, but it is disproportionate for a two-parameter label tool and crowds out basic parameter documentation.

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

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

The description is complete on the error path, but for a mutation tool with no output schema and zero schema coverage it should also say what a successful call returns and what color accepts. An agent could still call it correctly, but it would be guessing about color and about the response shape.

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 description coverage is 0%, so the description must carry the full burden, and it only partly does. 'Idempotent by name' usefully establishes that name is the identity key, but the color parameter is never mentioned at all, and neither parameter's format or constraints are explained.

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

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

The description opens with a specific verb and resource, creating or updating a label, and adds the key semantic that operation is idempotent by name. It doesn't name list_labels or any sibling as the read counterpart, so sibling differentiation is left implicit.

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 clarifies that update and create are the same call, identifying the name as the upsert key, and it gives explicit guidance for the billing-refusal path. It offers no guidance on when to use this instead of list_labels or on naming and color conventions.

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/closed-world, yet the description adds real behavioral facts: it returns `state` plus an `instruction` meant to be followed verbatim, including what to say to the human. It also discloses that the value is recomputed from server state each call, so nothing needs to be cached across sessions.

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?

Well front-loaded: purpose, when to call, return shape, freshness guarantee, then a caveat. Slightly redundant — 'nothing you need to remember between sessions' restates the restart/runtime/week-later claim, and the closing 'never guess' line echoes the authoritative-answer claim.

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-value burden and does so: one `state` and one `instruction`, plus a directive on how to act on it. Combined with the annotations, an agent has everything needed to call and use 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?

Zero parameters, so there is nothing to disambiguate and the baseline 4 applies. The description instead spends its words on the response contract, which the missing output schema makes worthwhile.

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 statement of what it reports: the workspace's position in onboarding plus the next step. It doesn't name a competing sibling (none of the listed tools overlaps with setup), but 'the ONLY authoritative answer' does draw a hard line against documentation-derived answers.

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 triggering conditions (human asks to set Retasc up or finish setup, just-connected, uncertainty about completeness) and an explicit negative rule: never guess onboarding steps from previously read documentation. An agent has no ambiguity about when to reach for this.

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 destructiveHint=true/idempotentHint=true annotations by spelling out exactly what is destroyed vs preserved: row kept so past work stays attributed, access gates dropped, and cascading terminal retirement of the member's agents with revoked keys and deleted strays. It also discloses reversibility path (reactivate_member, re-auth via GitHub) and the permission model, which 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 with the core action and effect, then layers cascade, reversibility, the sibling alternative, authorization, and failure modes in a logical order. It is dense and heavily capitalized, which costs a little readability, but nearly every clause is load-bearing.

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, permission-gated mutation with no output schema, the description covers effect scope, cascade consequences, reversibility, authorization requirements, and error outcomes. Nothing an agent needs before calling it 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% and there is only one parameter, so the schema already carries the baseline. The description still adds provenance ("from list_members/whoami") and the failure mode for an id belonging to another org (NOT_FOUND), which meaningfully disambiguates the value to supply.

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 ("Offboard a PERSON from the org") and immediately scopes it as person-only, naming retire_member as the agent alternative and reactivate_member as the inverse. An agent can distinguish it from retire_member, reactivate_member and list_members 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?

Explicit when-to-use (person offboarding), when-not ("For an AGENT, use retire_member instead — suspending an agent is rejected"), plus authorization preconditions (caller's human principal must be active owner or admin, admins limited to ordinary members) and hard refusals (self, last active owner, cross-org → NOT_FOUND).

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/destructive, yet the description adds substantial context: the semantics of `capped: true` (lower-bound figures during rollup backfill), the fact that `lifetimeMeteredEstimateUsd` is a diagnostic and not an amount owed, and that `pendingUsd` matches the Dash's PENDING. This is exactly the interpretive guidance an agent needs for a metrics 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?

Dense and front-loaded, with the core framing in the first clause and the sibling alternative named mid-paragraph. It is long, but nearly every clause disambiguates a field or a caveat; only the dual money-figure explanation is slightly verbose.

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 return values — and it does: reads, writes, ratio, rate card, both money figures with interpretations, and the `capped` flag. An agent can act on the result without further documentation.

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

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

The tool takes no parameters, so parameter semantics are trivially satisfied (baseline 4). The description instead spends its effort documenting return fields, which is appropriate given the empty schema.

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

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

Opens with a specific framing ('Usage METER for the org — activity volume, not a bill') that names the verb, resource, and the key distinction from billing. An agent immediately knows this reports metered activity rather than invoiced money.

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: 'For the full picture — subscription, charges and on-chain payments across every link — use `billing_summary`.' It also states a non-obvious usage fact (reading the meter is not charged), which removes hesitation about calling 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 readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context by disclosing what the call resolves to: identity type (agent vs human), org, and the API key's project scoping.

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?

A single sentence with no filler, listing the returned facts in a natural reading order. Nothing is padded or repeated from the title.

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 must carry the return content, and it names the three things returned (identity, org, project scope). Slightly more detail on field granularity would make it complete, but an agent has enough to decide and 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline of 4 applies. Schema coverage is 100% with an empty properties object, consistent with a no-argument call.

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 ('Return') plus the exact resource: the calling identity, its org, and the API key's project scope. It is clearly distinguishable from siblings like list_members or get_project, which return other entities rather than the caller's own identity.

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 this is a self-introspection call, but the description never says when to prefer it over list_members or get_project. For a zero-parameter identity call the inference is safe, but no explicit guidance is offered.

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