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

Annotations only declare readOnlyHint=true, and the description adds real depth: it writes nothing, names the cheap blocker set, gives the empirical failure rate, and carefully defines the semantics of `blocked` False as only 'nothing cheap is refusing yet.' It stops short of describing output shape or what happens on malformed inputs, but materially exceeds the annotation.

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

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

Front-loads the read-only scoping and the core distinction in the first line, then adds the caveat about what a clear preview means. The measured 49/159 statistic is persuasive but somewhat heavy for a tool description; otherwise tight and well-structured.

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

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

An output schema exists so return values needn't be described, and the description fully covers scope, safety, and the limits of the signal. The remaining gap is the undocumented confirmation and reviewer-request parameters, which an agent would have to guess at.

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% across 6 parameters, so the description must compensate and it only does so for one: `requested_risk_tier` is explained well (unset reads the finalizer's measured tier; explicit can only raise it). `confirm_high_risk`, `confirm_destructive_change`, and `reviewer_request_ids` are left entirely undocumented in both schema and description, so the compensation is partial.

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 ('preview what would block accept_review') and explicitly scopes it as the cheap, no-write half of the acceptance flow. The contrast with accept_review is unambiguous, so an agent can choose between them without opening either schema.

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

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

Explicitly says to run this before accept_review, enumerates the blocker classes it checks (lens running, target not review_ready, approval missing), and warns that a clear preview is not an acceptance. It also states what it does NOT cover — tree materialization, validations, gate, receipt verification — which is exactly the exclusion guidance an agent needs.

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

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

With no annotations, the description carries the full burden and delivers: idempotent behavior returning already_accepted, failure semantics (canonical repo untouched, task stays in review), risk-tier validation requirements, confirm_high_risk gating, and manager_correction refusal modes with error-code shapes. Rich beyond any structured field.

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 scope before descending into the manager_correction branch. Dense but mostly warranted; a few clauses (e.g., the receipt field enumeration) are verbose though they do provide useful structure.

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 mutation tool with no annotations, 10 params at 0% schema coverage, and an output schema, the description supplies the preconditions, side effects, idempotency, and error behavior an agent needs. The output schema covers returns, yet the description still names the receipt contents for clarity.

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% across 10 params, so the description must compensate. It thoroughly documents manager_correction's object shape, include_card values, and confirm_high_risk/risk-tier behavior, but leaves risk_signals, reviewer_reports, requested_risk_tier, reviewer_request_ids, and confirm_destructive_change unexplained.

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+resource+scope: 'accept one review_ready request, phase 2,' and details the promotion/finalization actions it performs. This clearly distinguishes it from siblings like aiworkhub_agent_accept_preview (phase 1) and aiworkhub_task_reject_review.

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?

Explains the precondition flow (re-run gates, compare hashes before promoting) and contrasts the manager_correction path against 'rejecting it.' However, it never explicitly names reject_review or accept_preview as alternatives with a clear 'use X when Y' rule, leaving some routing to inference.

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

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

No annotations are provided, so the description carries the full burden. 'Terminate' implies a destructive, likely irreversible operation, but the description never says whether the process is killed forcefully, what the two gates are, what happens if a gate fails, or whether authorization is required. 'DUAL-GATED' hints at a safeguard without disclosing its behavior.

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

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

It is a single short sentence with the action front-loaded, which is efficient. But the terse 'DUAL-GATED' label consumes prime space with opaque jargon rather than information, so brevity here costs clarity.

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 control-plane operation with no annotations and 0% schema coverage, the description leaves critical gaps: which task/process states are eligible, what the dual gate enforces, and what the effect on the recorded process group is. An output schema exists, so return values need not be described, but the operational contract is not.

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 compensate, yet it only alludes to a recorded request without explaining the required request_id format, whether it must reference a live process, or what the 'reason' field's default 'owner_cancelled' means or which values 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?

The verb 'terminate' and resource 'one exact process group recorded by this server' give a recognizable action, and the past-tense framing distinguishes it from aiworkhub_agent_list_processes (a read). However, 'DUAL-GATED' is unexplained jargon that an agent cannot decode, and the scope phrase 'recorded by this server' is vague about which server/bookkeeping is meant.

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

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

There is no statement of when to cancel versus when to retry, recover, or leave a task alone, even though siblings such as aiworkhub_agent_retry_finalization and aiworkhub_task_stale_recovery_recommend exist. No prerequisites, no mention of which task state permits cancellation.

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's 'READ-ONLY' claim merely repeats readOnlyHint=true rather than adding context. It does not explain what 'bounded' means in practice (truncation, log-byte capping), what happens if output exceeds the bound, or what the collected evidence actually contains.

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 front-loaded sentence with no filler, and the safety marker leads. It is efficient, though efficiency here partly reflects under-specification rather than disciplined editing.

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

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

An output schema exists, so return values need not be explained, but with two undocumented parameters at 0% coverage and no usage or lifecycle context, the description leaves real gaps for an agent trying to call it correctly.

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

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

Schema description coverage is 0%, so the description must carry both parameters; it never mentions request_id at all, and only vaguely gestures at max_log_bytes through the word 'bounded'. An agent gets no format or semantics for the required identifier.

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

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

Names a verb ('collect') and a resource ('worker output'/'review-readiness evidence'), so the general intent is inferable, but 'review-readiness evidence' is opaque jargon and nothing distinguishes it from adjacent tools like aiworkhub_agent_task_status or aiworkhub_agent_accept_preview.

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

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

There is no statement of when to call this versus the many sibling agent/task tools, and no prerequisite or lifecycle context (e.g., after a worker completes). The only guidance is the 'READ-ONLY' prefix.

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

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

With no annotations, the description carries the load well: it discloses the dual env gates, that it starts a shell-free child process, the full validation chain (task card, runner, topic, pending state, write scope, collision guard, adapter, process limit), and that timeout_seconds does not enforce a wall-clock deadline. It omits what happens on failure and the irreversibility of launching a live process.

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 dual-gate constraint and the core action in the first sentence, then handles optional-parameter semantics in a compact block. A few parentheticals (e.g. the 'launcher refused any value that differed' aside) are denser than necessary but still informative.

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?

It references launch_identity_derivation in the reply, and an output schema exists so return values needn't be spelled out. But for a process-launching side-effecting tool with no annotations, gaps around model/owner_prompt meaning and failure behavior leave the picture incomplete.

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% across 7 parameters, yet the description explains the non-obvious ones (runner, topic, adapter_id optionality and derivation precedence, timeout_seconds being non-enforcing). It says nothing about model, owner_prompt, or task_id, so a third of the parameters remain undocumented anywhere.

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: 'launch one exact local Claude/Codex worker process' for a single task. That is clearly distinguishable from the read-only launch-queue siblings and from task-creation tools. It does not name alternatives explicitly, keeping it 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?

It gives prerequisites (both AIWORKHUB_ALLOW_LAUNCH=1 and AIWORKHUB_ALLOW_WRITES=1) and explains when to omit vs pass runner/topic/adapter_id. However, there is no guidance on when to choose this tool over siblings like aiworkhub_task_queue_request or aiworkhub_launch_queue_evaluate_readonly, so usage is only 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 readOnlyHint=true, so 'READ-ONLY:' is largely redundant repetition of structured data. The description does add two genuinely new behavioral facts — results are 'latest' processes and legacy records require the full detail mode — but says nothing about ordering, pagination, or result volume beyond the limit default.

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 front-loaded sentence with the read-only guarantee first and the parameter caveat second. Compact with no filler, though the brevity is partly under-specification rather than efficiency.

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

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

An output schema exists so return values need no explanation, and both parameters are optional with defaults, making a correct call possible. However, the agent still cannot tell what a 'process' record represents or when the legacy/full mode applies.

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 carries the full burden. It explains detail='full' (legacy records) but never contrasts it with the 'summary' default, and the `limit` parameter is completely unaddressed in both schema and description.

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

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

States a verb and resource ('summarize latest processes'), but what a 'process' is in this system is never defined, and the name says 'list' while the description says 'summarize'. No sibling is named, even though the catalogue contains many list-style tools (aiworkhub_task_list, roadmap_list) that an agent could confuse it with.

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

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

Only guidance given is a parameter hint ('use detail=full for legacy records'), not a when-to-use-this-vs-alternatives statement. No exclusions, prerequisites, or routing to any sibling tool are provided.

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

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

With no annotations, the description carries the full burden and delivers rich detail: it states the provider/model is never relaunched, that prior artifacts are revalidated, that re-entry is deterministic, that the lane is never derived from candidate output, and that the refusal path writes no event or card transition. These are exactly the operational traits an agent cannot infer.

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 operation is front-loaded in the first line, and every subsequent paragraph adds distinct eligibility or refusal detail. It is dense and jargon-heavy, but for a coordinator/write-gated tool with complex semantics, the length is largely earned.

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 annotations, an output schema exists, and the tool is complex and write-gated, the description covers the call contract, eligibility gates, failure modes, adapter restrictions, and state-preservation guarantees. An agent has everything needed to decide whether to call it and what to expect.

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 description must compensate. It explains the non-obvious `validation_lane` parameter in depth (opt-in for manager host, forced backend, adapter restriction) and implicitly explains `request_id` via 'retained finalization request' and `task_id` via 'task identity revalidated'. The only small gap is no explicit format hint for the two IDs.

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: 'retry one retained finalization request' with a 'COORDINATOR/WRITE-GATED' qualifier. An agent can tell it is a retry operation for finalization, but the description never names which sibling tools (e.g., aiworkhub_task_retry_terminal or aiworkhub_agent_accept_review) are alternatives, so sibling differentiation is missing.

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

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

Explicitly defines when the tool is eligible: validation failures only for the `validation_exec_scratch_unavailable` condition, `scope_rejected` requests, and the `validation_lane='manager_host'` opt-in for VS Code LM adapters only. It also specifies when it is refused: CLI adapters get `validation_lane_forbidden_for_adapter:<adapter>` up front. This is unusually thorough when/when-not guidance.

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

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

readOnlyHint already covers the safety profile, so credit goes to the added context: which fields fold vs. stay exact per mode, the byte-cost measurement (avg 11 KB/call, max 33 KB) and the card_sha256/card_bytes receipt. The dense field-name inventory is hard to parse but materially describes response shape and volume beyond the annotation.

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

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

Front-loading the READ-ONLY statement and the default mode is good. The middle is a single sprawling paragraph of internal field names (terminal_failure, template_provenance.expanded_contract, worker_mcp_gate) that is hard to scan and could be condensed into a compact per-mode list.

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

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

An output schema exists, so return shape needn't be re-explained, yet the definition covers detail modes and folding well. It omits how to obtain request_id and any routing versus the many overlapping task-inspection siblings, leaving real gaps for an agent deciding whether to call this tool.

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

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

Schema description coverage is 0%, so the description carries the full burden. It thoroughly characterizes the detail enum behavior across summary/evidence/full, but never explains request_id at all — neither its meaning nor where the agent obtains one — leaving the sole required parameter undocumented.

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: 'inspect one launched process and its authoritative task card', and the READ-ONLY prefix sets scope immediately. It does not explicitly contrast with near-siblings like aiworkhub_task_show or aiworkhub_dashboard_task_detail, so an agent must infer which inspector to use.

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 explains the three detail levels and their default, which is genuinely useful for choosing how much to request. It gives no guidance on when this tool is preferred over task_show, dashboard_task_detail, or agent_list_processes, and no preconditions for obtaining request_id.

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?

No annotations are provided, so the description carries the full behavioral burden and does not meet it. It hints that the operation is bound to the server's active repo root (no path argument needed), but never says what files are modified, whether default behavior is a no-op/dry run, or that this mutates the working tree.

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 no padding, so it is structurally clean and front-loaded. However the brevity is under-specification rather than economy — there is simply nothing there to be concise about.

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

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

An output schema exists, so return values need not be described. But for a mutation tool with zero annotations, 0% parameter coverage, and an ambiguous default-off `write` flag, the description is far too thin to let an agent call it safely or 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%, so the description must compensate for two undocumented parameters and does not. The enum values are self-describing filenames, but the `write` boolean with default false — the single most consequential parameter (dry-run vs. real write) — gets no explanation in either schema or description.

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

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

The description leans on the name's verb 'apply' and only supplies a location ('the server's active repository root'), never stating what resource is being applied — agent instruction files (AGENTS.md / CLAUDE.md / copilot-instructions.md) into the repo. It reads as a restatement of the tool name plus a positional qualifier, so an agent learns little about the actual action.

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

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

No when-to-use guidance and no mention of the obvious alternatives aiworkhub_agent_tool_instruction_preview or _inspect, which exist to preview the same change. The critical branch condition — that `write` defaults to false, implying a dry-run unless explicitly enabled — is never called out.

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?

No annotations are provided, so the description must carry the full behavioral burden. It discloses the repository-root scope and that the operation is MCP-bound, but it does not state whether the inspection is read-only, what files are read, whether access requires permissions, or what the output contains.

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 a single short sentence, which is concise, but it is under-specified rather than efficiently informative. The cryptic "MCP-bound" prefix does not compensate for the missing object of inspection.

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

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

An output schema exists, so return values need not be explained. However, with no annotations, an undocumented provider parameter, and no differentiation from closely related preview/apply siblings, the description is not complete enough for an agent to select and invoke the tool confidently.

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% and the single required parameter, provider, has an enum of instruction-file names. The description never mentions the provider parameter, the enum values, or how provider selection affects the inspection, so it adds no meaning beyond the schema.

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

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

The description names an action, "inspect," and a scope, "the server's active repository root," but it does not state what is being inspected or why. The tool name implies agent instruction inspection, yet the description itself leaves the resource vague and does not differentiate it from sibling tools such as aiworkhub_agent_tool_instruction_preview and aiworkhub_agent_tool_instruction_apply.

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

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

There is no explicit guidance on when to use this tool versus the related preview or apply tools. The description mentions the active repository root, implying context, but it provides no usage conditions, prerequisites, or exclusions.

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

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

With no annotations, the description must carry the behavioral burden. It usefully states the repository-root binding behavior and the MCP/CLI scope difference, but it does not explicitly say whether the preview is read-only, has side effects, or requires permissions.

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 concise and front-loads the MCP-bound scope. The CLI comparison sentence is somewhat tangential but still reinforces the repository-root constraint rather than obscuring the main point.

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?

Because an output schema exists, return values need not be described. However, for an instruction-preview tool with no annotations, the definition should more clearly state what preview means and when it should be chosen over inspect/apply.

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 description adds important meaning beyond the schema by clarifying that `provider` is an instruction-file target, not a model provider, and by pointing to the schema for valid filenames. It does not explain the default/null behavior when `provider` is omitted, but it materially improves interpretation of the sole parameter.

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

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

The description implies a preview operation tied to instruction-file targets, but it never plainly states what is being previewed or what the tool returns. It also lacks explicit differentiation from sibling tools `aiworkhub_agent_tool_instruction_inspect` and `aiworkhub_agent_tool_instruction_apply`.

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

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

There is no guidance on when to use preview versus inspect or apply, and no preconditions such as when to call it before applying changes. The MCP/CLI repository-root distinction is useful context but not usage guidance for the MCP 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?

With no annotations, the description carries the full behavioral burden, and it does disclose this is a WRITE. However, it never explains what acknowledging does (removes the batch from a queue? confirms processing?), whether it is idempotent, what failure modes exist, or what a lease_id represents, all of which are essential for a state-changing 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?

A single tight sentence with a front-loaded 'WRITE:' action marker that efficiently flags the mutation semantics. It wastes no words, though the brevity contributes to its under-specification.

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

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

An output schema exists so return values need not be described. But for a two-parameter mutation tool with zero annotation coverage and zero schema descriptions, the definition leaves the lease semantics, prerequisites, and effect of the call entirely unexplained.

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 compensate and largely does not. 'One exact callback batch' loosely maps to batch_id, but lease_id — the more consequential parameter implying a lease/hold — is never mentioned, nor is any format or constraint given for either.

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

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

The description names a specific verb (acknowledge) and resource (a callback batch) and scopes it to a batch returned to this same verified Claude manager session. It is clearly distinguishable from the read-oriented aiworkhub_claude_callback_wait sibling, though it never names that sibling explicitly to route the agent.

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

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

There is no explicit when-to-use or when-not-to-use guidance. The 'returned to this same verified Claude manager session' phrase weakly implies this follows a callback_wait, but no alternative, ordering, or prerequisite is stated, leaving the agent to infer the 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?

With no annotations, the description carries the full disclosure burden and does so well: it flags that the call BLOCKS, that a prior batch is acknowledged via ack_batch_id/ack_lease_id, and that an unacknowledged lease is retried rather than lost. It still omits details such as what happens when timeout_seconds elapses or whether an empty ack is allowed.

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

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

Two tight sentences, front-loaded with the key blocking trait, and the acknowledgment mechanics follow immediately. Backticked identifiers aid scanning; nothing is redundant, though the 'BLOCKING READ/CLAIM' prefix plus 'wait' slightly overlaps.

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?

Because an output schema exists, return values need not be described, and the description covers the essential loop semantics (wait, ack, retry). The main gap is the unmentioned timeout_seconds parameter and any guidance on long-poll behavior across repeated calls.

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% across 3 parameters, so the description must compensate. It explains why ack_batch_id/ack_lease_id are passed (to acknowledge the previous batch) and where those values come from, but timeout_seconds is never mentioned despite a non-obvious default of 240.

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 ('wait for a callback') plus a scope ('for this verified Claude Code manager session'), and it names the sibling tool aiworkhub_claude_callback_ack, which distinguishes it from the closest alternative. The leading 'BLOCKING READ/CLAIM' label is somewhat ambiguous (is it reading or claiming work?), keeping it just short of 5.

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

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

It gives clear context for when to invoke — waiting for a callback on a verified manager session — and names an alternative path for acknowledging (passing ack ids here, or calling aiworkhub_claude_callback_ack). It does not spell out when NOT to use this tool or how to choose between the two ack paths, so it stops short of the 5 bar.

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?

No annotations are provided, so the description carries the full burden, and it does substantial work: it declares the tool never writes, never enables writes, never launches, and that env values never appear in entries so output is safe to log. What is missing is failure behavior (e.g., unknown repo) and how the entry limit truncates results.

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

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

The purpose statement is front-loaded and each following sentence earns its place by establishing a distinct safety guarantee. The reference to 'core.read_audit_log' and 'authority flags' is mildly implementation-facing but supports the read-only 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?

An output schema exists, so return values need not be described, and the safety/loggability story is complete. However, for a tool that takes a repo selector and an entry cap, the absence of any parameter or scoping explanation leaves a real gap in the description's 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 description coverage is 0%, so the description must compensate for both parameters and does not: neither 'repo' nor 'max_entries' is mentioned. The only hint of limiting behavior is the schema default of 100, which the prose never explains.

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

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

States a concrete verb ('Return a read-only summary') and a specific resource ('the write-gate audit log'), which distinguishes it from the launch-queue and task audit-log siblings by scope. It does not name any sibling explicitly, so the differentiation is inferential rather than stated.

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

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

There is no when-to-use, when-not-to-use, or alternative-selection guidance. With siblings like aiworkhub_launch_queue_audit_summary_readonly, aiworkhub_task_audit_log_read, and aiworkhub_cli_adapter_report_readonly in the catalog, the agent is left to guess which audit surface this covers based on the phrase 'write-gate' 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?

With no annotations, the description carries the full burden and does so well: it discloses no audit entry, no task-queue mutation, no launch, env redaction including secrets, read-only regardless of the write gate, and the collision preflight's no-lock/no-claim behavior. These are exactly the behavioral traits an agent needs before invoking.

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 safety guarantee is front-loaded in the first sentence, and the remaining detail is dense but earns its place. It is slightly verbose but no sentence 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?

Since an output schema exists, return-value explanation is unnecessary, and the description covers behavioral semantics and the collision preflight thoroughly. The main gap is the lack of parameter-level meaning for five of the seven inputs.

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% across 7 parameters, so the description must compensate. It adds meaning for only two params (argv validated against the static allowlist, env redacted) while task_id, runner, topic, adapter_id, and repo remain completely undocumented in both description and 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: 'Return a validated launch PLAN without writing anything.' It further clarifies the wrapper (plan_dryrun(audit=False)) and explicitly contrasts with write behavior ('launches NOTHING'), which distinguishes it from siblings like aiworkhub_agent_launch_task.

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 tool is for validating/dry-running a command plan, and the 'read-only holds regardless of write gate' note gives useful context. However, it never explicitly states when to prefer this over alternatives such as aiworkhub_agent_launch_task or the write variants, leaving the use-vs-alternative decision 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?

No annotations are provided, so the description must carry behavioral disclosure. 'Read-only' is a useful trait, and returning both a validated plan and audit summary is a behavior, but it omits permission requirements, any side effects, rate limits, or error behavior.

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 single sentence is front-loaded and free of filler, but its size is not appropriate for a tool with eight parameters and no schema descriptions. It is concise to the point of under-specification.

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 tool has 8 parameters, 5 required, 0% schema descriptions, no annotations, and an output schema. The description covers only read-only and combined return, leaving an agent without guidance on required inputs or operation, so it is substantially incomplete.

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 8 parameters, so the description must compensate. It contains no parameter-level information—task_id, runner, topic, adapter_id, argv, env, repo, and max_audit_entries are all undocumented in prose.

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 it is a read-only call returning a validated plan and an audit summary, which distinguishes it from sibling plan_readonly and audit_summary_readonly by combining both outputs. However, it doesn't explicitly name those siblings or clarify what 'validated' entails, so it is clear but not maximally specific.

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 use when an agent needs both a plan and an audit summary in one read-only call, but provides no explicit when-to-use guidance or exclusions relative to the separate sibling tools. Alternatives are left for the agent to infer.

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

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

With readOnlyHint already present, the description still adds substantial context: it names the exact read-only taskctl commands used, explicitly excludes write commands, and clarifies it never launches agents or processes. It also explains stale_processing's default threshold and that runner_mismatch is a pure local replica of a named function.

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 READ-ONLY and the five-facet summary, then details each facet. Slightly repetitive on the no-mutation/never-launch guarantees, but every element is informative and ordered well.

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

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

An output schema exists so return values needn't be explained, and the description fully covers the read-only contract and facet meanings. The main gap is the undocumented limit and topic parameters, but overall it's sufficient to call the tool correctly.

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

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

Schema coverage is 0%, so the schema does no documentation work. The description clarifies stale_processing_hours (default 24h) but says nothing about limit or topic semantics, leaving two of three parameters undocumented.

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: aggregates five named completion-inbox facets for Codex orchestration, and enumerates each facet (review_queue, operational_failures, stale_processing, runner_mismatch_warnings, latest_validation_facts). It implies a combined view versus individual sibling tools but doesn't name those siblings.

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

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

The word 'combined' and the list of facets imply this is a convenient aggregate over separate queries, but it never explicitly says when to use this versus e.g. aiworkhub_task_review_queue or aiworkhub_task_stale_recovery_recommend. Usage is inferable but not 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?

readOnlyHint=true is already declared in annotations, so 'READ-ONLY' adds nothing new. The description does not say what constitutes drift, whether it compares against a stored baseline, whether it is expensive, or what it does when drift is found. It gives no behavioral context beyond the annotation it restates.

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 front-loaded sentence with no padding and the safety mode stated up front. It is efficient, though the brevity leans toward under-specification rather than tightness.

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

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

An output schema exists, so return values needn't be spelled out, and with zero parameters there is little surface area to cover. Still, the description never explains what 'drift' covers or what scope the check spans, leaving the agent to infer from the name alone.

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

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

The tool takes zero parameters, so there is no parameter semantics burden on the description. Baseline 4 applies; nothing is missing or misleading on this dimension.

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 verb 'detect' and object 'instruction drift' are present, but 'managed provider/worker instruction drift' is domain jargon that isn't unpacked, so an agent cannot tell precisely what condition is being checked. Nothing distinguishes it from siblings like aiworkhub_agent_tool_instruction_inspect or aiworkhub_agent_tool_instruction_preview, which sound like they operate on overlapping subject matter.

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

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

There is no statement of when to run this check, what triggers it, or why an agent would pick it over the many instruction/skill/recipe siblings. Only the 'READ-ONLY' prefix hints at safe invocation, and that is already covered by annotations, not usage guidance.

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

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

Annotations already declare readOnlyHint=true, so the summary's 'READ-ONLY' prefix is partly redundant, but the description adds real value beyond the annotation by disclosing that it probes cached observability and deliberately does not build the full queue snapshot or mutate repository state. It does not discuss error surfaces (e.g., what a not_initialized status looks like), which is a minor gap; an output schema exists so return shape needn't be described here.

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 paragraphs, front-loaded with the purpose and then the routing guidance. The only waste is minor redundancy between 'READ-ONLY' and 'without ... mutating repository state', which restates the annotation.

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 parameterless read-only probe with an output schema and readOnly annotation, everything an agent needs is present: what is checked, the cost profile (fast/lightweight), the sibling alternatives, and the precondition escalation path to initialize. Nothing material is missing.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline of 4 applies. The description correctly implies no input is needed by describing the check as scoped to the active repository.

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

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

The description names a specific verb set (storage readiness, manager identity, dispatcher health check) and an explicit scope (the active repository). An agent can distinguish it from aiworkhub_dashboard_snapshot and aiworkhub_dashboard_initialize without opening any schema. It also flags the operation as fast and lightweight, which is the distinguishing trait.

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

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

It explicitly routes usage: use this for connection-banner polling or pre-initialization checks; use snapshot when task queue counts, process rows, or cost summaries are needed; use initialize when storage reports not_initialized. That covers when-to-use, when-not, and the named 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?

With no annotations, the description carries the full burden and does so: it discloses repo-root binding, fail-closed repo_id verification against an existing manifest, idempotency, non-destruction of legacy files, and telemetry invalidation. That is exactly the mutation-risk context an agent needs before invoking a write tool.

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

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

Front-loaded with the write classification and purpose, followed by the trigger condition before the mechanics, which is the right ordering. The final sentence is a long clause chain covering five separate behaviors, which is dense though not wasteful.

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

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

An output schema exists so return values need not be explained, and the description covers the operational envelope: prerequisite state, failure mode, idempotency, and non-destructive guarantees. Nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100% and the single repo_id parameter is fully documented in the schema, including the fail-closed default behavior. The description restates the manifest-match requirement but adds no new syntax or format detail, so the baseline 3 applies.

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

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

States a specific verb (initialize or repair) and a specific resource set (the .aiworkhub stores and Source Graph directory of the active repository). The 'USER WRITE' prefix and the explicit contrast with aiworkhub_dashboard_health / aiworkhub_dashboard_snapshot make it distinguishable from siblings 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 an explicit trigger condition: use when aiworkhub_dashboard_health reports storage not_initialized. Also names the alternatives for read-only status checks, so the agent knows both when to pick this tool and when not to.

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, so the safety profile is known; the description still adds useful context that it opens the KB SQLite store read-only, does not mutate entries, and does not bump usage counters, plus that only canonical entries are listed. This is genuine added signal, though the read-only nature is restated three times.

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?

Only three sentences and the resource scope is front-loaded before the alternative routing. Minor waste from repeating 'READ-ONLY' in the prefix and again as 'read-only mode without mutating entries or usage counters'.

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, read-only list tool with an output schema and clear annotations, the description covers purpose, ordering ('newest'), scope (active repository), canonical filtering, and alternatives. 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% and the single 'limit' parameter is documented in-schema with its default and 1..500 clamp. The description adds nothing about parameters, so baseline 3 applies despite the otherwise strong narrative.

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), resource (newest canonical Knowledge Base entries) and scope (active repository). It also explicitly distinguishes itself from aiworkhub_dashboard_memory and aiworkhub_dashboard_sessions, so an agent can route correctly without opening sibling 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?

Explicitly says 'Use this to browse repository Knowledge Base articles, categories, and tags' and names two alternatives with the condition that selects each. The when-to-use mapping is complete for the dashboard KB read case.

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

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

Annotations already declare readOnlyHint=true, but the description adds substantive detail: it opens the repository memory SQLite database in read-only mode and never increments access counters or mutates rows. That is real behavioral context about side effects a caller might otherwise worry about, not a restatement of the annotation.

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

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

Two sentences, both front-loaded: the read-only scope and resource come first, then the alternative routing. Every clause carries information, and there is no redundant repetition of 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 one-optional-parameter read tool with annotations and an output schema present, the description covers purpose, alternatives, and the non-mutation guarantee. Nothing needed 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 description coverage is 100% and the single 'limit' parameter is already documented with its default and 1..500 clamp. The description only implies ordering via 'newest' and adds no syntax or format information beyond the schema, 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 (list), resource (newest canonical AI Memory entries) and scope (active repository) in the first line. It also names the sibling tools that cover adjacent data (sessions, Knowledge Base), so an agent can distinguish this from aiworkhub_dashboard_sessions and aiworkhub_dashboard_kb without reading either schema.

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

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

Explicitly says 'Use this to browse stored AI Memory rows and lifecycle statuses in the dashboard' and then names the alternatives for sessions and KB entries. The routing condition is stated directly rather than left 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?

With no annotations, the description carries the full burden and does well: it discloses the write nature, that a model-settings lock is acquired, that expected_revision is verified, and that persistence is atomic. It stops short of stating auth/permission requirements or whether a toggle is reversible, which are the remaining gaps for a mutation tool.

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

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

Front-loaded 'USER WRITE' marker, then a purpose sentence, then usage/alternatives, then concurrency behavior. Two dense sentences with no wasted text and correct ordering of decision-relevant 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?

Output schema exists, so return values are already covered; the description supplies the concurrency, locking, and alternative-tool context an agent needs before calling a write operation. Nothing essential is missing for correct invocation.

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

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

Schema coverage is 100%, so each parameter (including the model-under-adapter relationship and expected_revision fail-closed behavior) is already documented. The description reinforces the three-level switch concept (provider → adapter → model leaf) but adds little syntax or meaning beyond the schema, so the baseline 3 holds.

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 (update) plus resource (one provider, adapter, or model routing switch) and scope (active repository). The 'USER WRITE' prefix and the reference to 'model routing switch' clearly separate it from aiworkhub_dashboard_settings_update (repository feature flags) without needing the schema open.

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 what it is for (enable/disable a provider, transport adapter, or model leaf) and gives alternatives: call aiworkhub_dashboard_settings first to read model_policy/revision, or use aiworkhub_dashboard_settings_update for feature flags. Prerequisite and sibling routing are both spelled out.

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?

No annotations exist, so the description carries the full burden and does it well: requires confirm=True, refuses rows in converting status, sets status to archived, emits an audit event, and returns the updated item. It also states the record is not deleted, which is the key safety fact for 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?

Two tight sentences: the mutation and its non-destructive nature are front-loaded, followed by the sibling routing and the behavioral caveats. No filler.

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

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

An output schema exists, yet the description still notes the updated item is returned. Confirm requirement, status restriction, audit behavior, and reversibility path are all covered, leaving nothing an agent needs 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 confirm and reason are already documented; however, the description adds a genuine constraint on needfix_id (rows in converting status are refused) that the schema does not convey. Confirm semantics are largely repeated from 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 (archive), resource (NeedFix item), and scope (one non-converting item, record retained). It also names what it is not: it does not delete the stored record, and the siblings restore/purge are named for contrast.

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

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

Explicitly says when to use it (move an inactive or obsolete row out of the active inbox) and routes to alternatives with conditions: restore for returning to active, purge for permanent deletion.

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

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

With no annotations, the description carries the full disclosure burden and does well: it says a write gate is required, that kind synonyms are normalized, that either a new or deduplicated row is persisted, and that a capture receipt is returned. It still leaves the deduplication criteria implicit, which is the main remaining behavioral 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 core operation is front-loaded in the first sentence, followed by usage guidance and behavioral details. Every sentence adds useful information without repetition or 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?

The tool has an output schema, so it need not explain the receipt format, and the schema fully documents parameters. The description covers the write gate, deduplication behavior, and sibling alternatives, leaving only the precise deduplication rule unspecified.

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

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

Schema description coverage is 100%, so the schema already explains all seven parameters, including kind normalization, severity levels, truncation limits, and include_item. The description adds only the normalization/deduplication context, 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 gives a specific verb and resource: capture a new NeedFix item or deduplicate against an existing live row. It also explicitly distinguishes this tool from aiworkhub_dashboard_needfix_update and aiworkhub_dashboard_needfix_transition, so an agent can select it without inspecting the schema.

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

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

It states exactly when to use this tool: to record a new bug or proposal in the NeedFix inbox. It names the sibling alternatives for editing and status changes, and adds the prerequisite that an open write gate is required.

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

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

With no annotations, the description carries the full burden and does well: it names the mutation (creates the task card in the task store), the state transition (NeedFix item to task_created), the confirmation gate (confirm=True plus matching plan_digest), and the non-effect ('never spawns a worker process'). It does not cover failure behavior on digest mismatch or whether the conversion is reversible, which keeps it short of a 5.

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

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

The write-nature and the core action are front-loaded in the lead sentence, followed by the two routing constraints. Two dense sentences with no filler or restated 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?

An output schema exists, so return values need not be explained, and the description covers the prerequisite, the side effects, and the worker-free guarantee an agent needs before mutating state. Missing only edge-case information such as recovery from a stale or mismatched plan_digest.

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 confirm, needfix_id, plan_digest and task_plan are already documented in structured form; the description largely restates confirm=True and the plan_digest requirement. The only real addition is the 'matching' digest constraint implying runtime validation, which is marginal at this coverage level, so the baseline of 3 applies.

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

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

States a specific verb and resource ('convert an accepted NeedFix item into a canonical task card') plus the key scope limit ('without launching a worker'). It explicitly distinguishes itself from both siblings, aiworkhub_dashboard_needfix_convert_preview and aiworkhub_dashboard_needfix_link_existing_task.

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 ordering ('Call ...convert_preview first to obtain the required plan_digest') and an explicit alternative with the condition that selects it ('use ...link_existing_task instead when a finished accepted task already resolves the item'). Both the when and the when-not are 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 readOnlyHint annotation, it discloses that the preview is cached in memory with a signature, that no task is created, and that no durable store state is mutated — exactly the mutation-risk questions an agent would have. It also surfaces that the returned plan_digest is a prerequisite input for commit, adding workflow-level 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?

Three sentences, front-loaded with the READ-ONLY marker and the core action, then ordering, then the no-mutation guarantee. Slightly dense in the middle sentence (two sibling references plus three inspection targets), but every clause carries operational 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?

An output schema exists, so return values need not be described; the description instead supplies the workflow position, the safety guarantee, and the downstream dependency (plan_digest required to commit). With 100% schema coverage and a matching readOnlyHint, nothing an agent needs to call this correctly is absent.

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

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

Schema coverage is 100%, so both `needfix_id` and the optional `task_plan` overrides are already fully documented in the schema. The description mentions the normalized card, validation requirements, and plan_digest only as outputs to inspect, not as parameter semantics, so it adds no meaning beyond the structured fields — 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 ('preview') and resource ('normalized task card and plan_digest for converting a NeedFix item into a task'), and explicitly names both the commit sibling it precedes and the detail sibling it differs from. An agent can distinguish this from `aiworkhub_dashboard_needfix_convert_commit` and `aiworkhub_dashboard_needfix_detail` 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 ordering ('Call this before aiworkhub_dashboard_needfix_convert_commit') and a routing rule for the alternative ('use aiworkhub_dashboard_needfix_detail to inspect the NeedFix item itself'). The when-to-use condition and the alternative are both named directly.

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, so the safety profile is covered; the description nonetheless adds useful detail by stating it validates needfix_id format and reads without mutating state, and that event history is bounded. It is partly redundant with the annotation ("READ-ONLY") but adds enforcement and scoping context beyond the structured fields.

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

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

Two short paragraphs, front-loaded with the read-only guarantee and the return shape, then the routing advice. The "READ-ONLY" prefix and "reads without mutating state" slightly duplicate each other and the annotation, but the text is otherwise tight.

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

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

An output schema exists, so return fields need not be enumerated; the description still signals the payload (detail fields + audit events). For a 2-param read tool with annotations and an output schema, 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?

Schema coverage is 100%, so both parameters (needfix_id format and event_limit clamping) are already documented in the schema. The description only adds that event history is bounded, which is marginal over what the schema states. Baseline 3 applies.

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

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

States a specific verb+resource: return one NeedFix item with full detail fields plus bounded audit event history. It names the sibling used for browsing (needfix_list) and the sibling used for conversion preview, so an agent can distinguish it without opening any schema.

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

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

Explicitly says when to use it (inspect a single item's description, scope, evidence, lifecycle events) and names the two alternatives with the condition that selects each. Nothing is left to inference.

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

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

With no annotations, the description carries the load and does well: it flags this as a write ('USER WRITE'), discloses the confirm=True gate, describes server-side validation (task must exist, be finished and accepted; integrated_commit verified against the repo), and states what is persisted (task link plus audit event). It stops short of error/failure semantics or permission requirements, which keeps it below 5.

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

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

Front-loaded with 'USER WRITE' and the action, followed by the discriminating alternative and the behavioral contract. Two sentences plus a clause, near-zero waste; slightly dense packing but nothing extraneous.

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

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

An output schema exists so return values need no explanation, and the description supplies the mutation gate, validation rules, and persistence side effects an agent needs before calling. Minor gap: no failure/error behavior or idempotency note for a write tool with no annotations.

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 all four parameters are already documented in the schema; the description largely restates the confirm requirement and the commit verification rather than adding new semantics. Baseline 3 applies when the schema already does the heavy lifting.

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 a NeedFix item to an existing finished, manager-accepted task in the same repository') with explicit preconditions on the target task. It also names the sibling it must not be confused with (aiworkhub_dashboard_needfix_convert_commit), so an agent can disambiguate without opening either schema.

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

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

Explicitly gives the selection rule ('use this when an already-completed canonical task resolves the NeedFix item') and names the alternative plus its distinct condition (create a new task card). The two branches are mutually exclusive and clearly 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 declare readOnlyHint=true, and the description's 'READ-ONLY' and 'reads the SQLite store without mutating state' largely restate that. It does add that listing is 'bounded' and pageable, but the actual bounds (limit clamped to 1..200, default excludes archived) live in the schema, so behavioral value beyond structured fields is modest.

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 with the read-only constraint and the verb front-loaded, then routing guidance. Slightly redundant between 'READ-ONLY' and 'without mutating state', which repeats the same point twice.

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

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

An output schema exists, so return values need not be described, and annotations cover the safety profile. Between the description's routing and the schema's fully documented parameters, an agent has everything needed to call this correctly.

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

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

Schema description coverage is 100%, so every parameter (kind, status, severity, include_archived, limit, offset) is already documented with defaults and clamps. The description only echoes the filter names at a high level and adds no syntax, valid-value, or interaction detail, 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 ('list ... NeedFix inbox items') plus scope ('bounded', filterable), and explicitly distinguishes itself from aiworkhub_dashboard_needfix_detail and aiworkhub_dashboard_roadmap_list. An agent can tell exactly what this returns versus its nearest siblings.

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

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

Gives explicit routing: use this to browse/page summaries, use needfix_detail to fetch full description/scope/provenance/audit events for one item, use roadmap_list for Roadmap items. The when-to-use-this vs when-to-use-alternative decision is fully spelled out.

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 carry destructiveHint=true, but the description adds real context beyond them: the confirm=True and non-empty audit_reason gates, the already-archived precondition, and the fact that a purge audit event with a row snapshot is written before permanent deletion. It does not cover what happens to links/tasks attached to the row, which is the main residual risk.

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 'DESTRUCTIVE' and a tight first sentence, then alternatives, then requirements. Slight redundancy: 'permanently delete' is stated twice and the final clause re-explains the already-given row requirement.

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

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

Output schema exists and annotations cover the safety profile, so the description needn't explain return values. It covers preconditions and audit side effects well; only the handling of dependent records on purge is unaddressed.

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 confirm, needfix_id and audit_reason are already documented. The description restates confirm=True and 'non-empty audit_reason', which corroborates but adds little new semantics. Baseline 3 applies.

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

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

States a specific verb and resource ('permanently delete one archived NeedFix row from the NeedFix table') plus a non-obvious side effect (retains an audit snapshot). It is immediately distinguishable from needfix_archive, needfix_restore and the dashboard purge siblings because it names the table and the single-row scope.

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: use needfix_archive first, or needfix_restore to recover an archived item 'instead of deleting it'. The precondition (row must already be archived) further gates correct usage.

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

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

With no annotations at all, the description carries the full burden and does well: it declares this is a user write, enumerates side effects (increments reopen_generation, restores NeedFix to accepted status, writes an audit event), and states the precondition of a verified archived/superseded link. It stops short of covering failure behavior or permission requirements, which is the only gap for a mutating 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?

Two paragraphs, front-loaded with the operation identity before the conditions and effects. Density is high and nearly every clause earns its place, though the long compound sentence about conversion/successor naming is heavier 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?

For a mutation tool with no annotations, the description supplies purpose, gating conditions, side effects, and the sibling alternative, and an output schema exists so return values need not be explained. Only error/failure semantics and permission requirements are left implicit.

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

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

Schema coverage is 100%, so baseline would be 3, but the description adds a semantic constraint the schema does not encode: needfix_id must point at a NeedFix whose linked task is verifiably archived or superseded, and confirm=True is mandatory rather than merely defaulted. That is meaningful signal beyond the field descriptions.

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 (reopen) on a specific resource (a NeedFix whose linked converted task was archived/superseded), and the 'USER WRITE' prefix signals the mutation class immediately. An agent can tell this apart from the generic needfix_transition sibling without opening any schema.

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

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

Explicitly says when to use it ('a converted task was superseded or archived without resolving the NeedFix so a new conversion can mint a successor -rN task') and names the alternative to use otherwise (aiworkhub_dashboard_needfix_transition for normal lifecycle changes). Prerequisites (confirm=True, a verified archived/superseded linked task) are stated up front.

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

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

With no annotations, the description carries the full burden and does most of it: it declares this is a write, requires confirm=True, requires the source row to be archived, and enumerates side effects (clears archived_at, writes target_status, records an audit event) plus the return of the updated item. It stops short of stating permission/auth requirements or what happens when the precondition fails, which is the only remaining gap for an unannotated mutation.

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

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

The write/reversibility nature and the primary 'use this to unarchive' instruction are front-loaded in the first two sentences, with the alternative and side effects following. Three sentences, no filler, every clause carries information.

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

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

For a three-parameter mutation with an output schema (so return shape needn't be described), the definition covers purpose, precondition, effects, and sibling routing. 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 description coverage is 100%, so all three parameters are already documented in-schema, and the description mostly restates them (confirm=True, target_status assignment). It adds slight value by framing target_status as an 'active non-terminal' status, but no syntax or validation detail beyond what the schema provides, 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 (restore/unarchive) and resource (archived NeedFix item) plus the resulting state (active non-terminal lifecycle status). It explicitly distinguishes itself from needfix_archive (the inverse) and needfix_transition (lifecycle advance of already-active rows), so an agent can pick it without opening schemas.

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

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

Gives both when-to-use and when-not-to-use with named alternatives: use this after aiworkhub_dashboard_needfix_archive, use aiworkhub_dashboard_needfix_transition for active items. It also states the precondition (row currently in archived status) that gates invocation.

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?

No annotations are present, so the description carries the full burden. It discloses that this is a USER WRITE that persists a state transition and audit event, requires confirm=True, and returns a transition receipt. It does not detail error conditions, reversibility, or rate limits, but for a write tool this is a strong disclosure.

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

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

Two sentences with zero waste: the first sentence states the purpose and mutation nature, the second covers usage, alternatives, and key behaviors. The critical 'USER WRITE' and confirm requirement 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?

Output schema exists, so return values are already documented. Given the 8-parameter complexity, the description covers purpose, usage alternatives, confirm requirement, persistence, audit event, and receipt. Nothing an agent needs to call correctly is missing.

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

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

Schema coverage is 100%, so the schema already documents all 8 parameters including the action enum and confirm flag. The description mentions the action list and confirm requirement, but adds no syntax or behavior beyond what the schema provides. Baseline 3 is appropriate.

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

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

States a specific verb+resource ('apply one confirmed lifecycle status transition to a NeedFix item') and explicitly names sibling tools for other operations (archive, restore, convert_commit). An agent can distinguish this from all other NeedFix tools without opening the schema.

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

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

Explicitly lists when to use this tool (triage, accept, reject, defer, mark duplicate, mark task_planned, resolve, recover conversion claim) and when to use alternatives (archive, restore, convert_commit). Also states the confirm=True requirement, leaving no ambiguity about invocation conditions.

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

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

With no annotations, the description carries the burden and does well: it discloses the 'USER WRITE' profile, the prerequisite of an open write gate, that changes persist with an audit event in the NeedFix store, and that a delta receipt is returned. It stops short of covering failure modes (e.g. missing or archived needfix_id, closed gate behavior) or whether unspecified fields are left untouched, which the schema only implies via defaults.

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

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

Two sentences, front-loaded with the write profile and the field scope before the sibling routing. Nothing is redundant and every clause carries decision-relevant 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 nine-parameter mutation tool the essentials are present: mutability boundary, gate prerequisite, persistence/audit side effects, and the sibling split for status changes. An output schema exists, so return shape need not be explained. Missing only edge-case behavior (unknown/archived item, partial updates on null fields).

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

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

Schema description coverage is 100%, so the schema already documents all nine parameters including clamping and length limits. The description's field enumeration mirrors the schema rather than adding syntax or validation detail, and it never mentions include_item or needfix_id semantics. 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 (update) and resource (NeedFix item) plus the exact field families affected (content and classification). It also names the two adjacent sibling tools (transition, capture) so the agent can distinguish this tool without opening schemas.

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

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

Explicitly enumerates which edits belong here (title, description, scope, kind, severity, tags, readiness_score) and routes lifecycle changes to aiworkhub_dashboard_needfix_transition and creation to aiworkhub_dashboard_needfix_capture. Both alternatives and their selection conditions are given.

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 meaningful context beyond the readOnlyHint: confirms roadmap_id format validation and that only Roadmap and task stores are read with no state mutation. Does not mention pagination or error behavior for an invalid id, but annotations already carry the safety profile so the added value is solid.

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 tight sentences with the READ-ONLY marker and capability front-loaded. Slight redundancy between the 'READ-ONLY' prefix and the closing 'reads ... without mutating state', but nothing wasteful enough to penalize heavily.

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

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

Output schema exists so return values need no explanation, yet the description still enumerates the payload shape. Safety profile, sibling routing, and validation behavior are all covered for a simple 2-parameter 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?

Schema description coverage is 100%, so both roadmap_id format and event_limit clamping (1..100, default 50) are already documented. The description only echoes the id validation, adding little beyond the schema — 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 ('return one Roadmap outcome') plus the exact payload contents (linked task progress, wave projection, audit events), and explicitly contrasts with aiworkhub_dashboard_roadmap_list for browsing. An agent can pick this tool over its sibling without opening a schema.

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

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

Explicit 'use this to inspect a specific Roadmap item's dependencies, linked tasks, and event log' followed by the selecting condition for the alternative ('use list to browse all'). Both when-to-use and the alternative are named.

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

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

Annotations declare readOnlyHint=true and the description reinforces and extends it: 'Reads the Roadmap and task stores without mutating state' tells the agent which stores are touched and that state is untouched. It also signals the result is 'bounded' and contains joined DAG progress/wave projection, which the annotation does not convey. Missing only detail on the bounding rule and any read cost.

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 padding. The read-only guarantee and the primary purpose are front-loaded, and the sibling routing follows immediately.

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

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

With a full input schema, a 100% description coverage, and an output schema present, the description does everything essential: scope, read-only guarantee, and alternative routing. The one loose thread is the unexplained 'bounded' limit behavior, but that is largely covered by the schema's clamp note.

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% — limit (clamped 1..200), offset, status filter, and include_archived are all documented with defaults and constraints. The description adds no parameter-level meaning, 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 bounded Roadmap outcomes') plus the enrichment it applies ('joined with task-DAG progress and wave projection'). This immediately separates it from aiworkhub_dashboard_roadmap_detail (single item) and aiworkhub_dashboard_needfix_list (different resource).

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 'Use this to browse Roadmap items, status counts, and wave readiness' and then names two alternatives with the conditions that select them (roadmap_detail for one item's full detail/audit events, needfix_list for NeedFix items). Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces this with concrete evidence of what is untouched ("never modifies session checkpoints or access state") and which store it reads (canonical transcript SQLite, opened read-only). Missing only secondary details like ordering guarantees or how the limit interacts with output, so not a 5.

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

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

Two short sentences, with the read-only constraint and scope front-loaded before the sibling routing guidance. Every sentence earns its place; nothing is repeated from the schema or annotations verbatim beyond a useful reinforcement of read-only 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?

An output schema exists and annotations cover the safety profile, so the description needn't explain return values; purpose, scope, and alternatives are all present. Slightly short of complete because it doesn't say anything about what a 'transcript document' contains or how results are ordered relative to the limit, which would help an agent interpret the call.

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 single 'limit' parameter is fully documented in the schema (default 100, clamped to 1..500, meaning of the value), so the schema carries the weight. The description says "newest" documents, which implicitly confirms ordering, but adds no further parameter meaning. Baseline 3 is appropriate at 100% 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?

States a specific verb and resource ("list the newest Session Manager transcript documents") plus scope ("for the active repository"). It also explicitly contrasts itself against aiworkhub_dashboard_memory and aiworkhub_dashboard_kb, so an agent can distinguish it from the nearest siblings without opening schemas.

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

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

Gives both the positive trigger ("inspect recent session continuity documents") and the alternatives with their conditions (memory for durable keys, kb for Knowledge Base articles). No inference is required to route between the three dashboard read tools.

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 annotation by stating it reads repository configuration files and status views 'without mutating durable state or starting background services' — a concrete behavioral guarantee about side effects that annotations alone 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-loads the READ-ONLY marker, then purpose, then routing guidance, then side-effect guarantees — every sentence carries information. Slightly dense in the final sentence, but no filler.

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

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

An output schema exists, so return values need no explanation here. The description covers purpose, sequencing relative to the update tools, sibling exclusions, and side effects — nearly complete for a zero-parameter read tool, with only minor detail (e.g. what a 'revision number' looks like) 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?

The tool takes no parameters, so there is nothing for the description to disambiguate and the baseline is 4. No parameter noise is introduced, which is correct 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 (return) and enumerates the exact configuration domains covered: repository feature switches, Source Graph policy, retention policy, and model routing policy. An agent can distinguish this settings-inspection tool from aiworkhub_dashboard_snapshot and the three settings_update siblings without opening any schema.

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

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

Explicitly gives the when: inspect current settings and revision numbers before calling aiworkhub_dashboard_settings_update, aiworkhub_dashboard_model_settings_update, or aiworkhub_dashboard_source_graph_settings_update. It also names the exclusion and the correct alternative — 'For queue state or task counts use aiworkhub_dashboard_snapshot 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?

With no annotations, the description carries the full behavioral burden and does so well: it labels the tool as USER WRITE, describes optimistic revision locking, notes atomic persistence on revision match, and discloses side effects such as starting/stopping Source Graph and initializing the context graph schema. These are exactly the mutation and concurrency traits an agent needs beyond 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?

The description is front-loaded with the write/atomicity warning, then moves directly into routing guidance and behavioral effects. Every sentence adds actionable information, with 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 two-parameter mutation tool with full schema coverage and an output schema, the description supplies the missing operational context: concurrency expectations, atomicity, side effects, and sibling alternatives. Nothing essential for correct invocation is left out.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds useful meaning by naming example feature keys (source_graph, context_graph) and tying them to observable side effects, though it does not enumerate all valid keys or explain the changes object beyond those examples.

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 precise verb and resource: atomically update repository-local feature switches. It explicitly distinguishes top-level feature switches from language/model routing switches and names the sibling tools to use instead, so an agent can route correctly.

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 direct usage guidance: use this tool to toggle top-level features like source_graph or context_graph, inspect current switches and revision with aiworkhub_dashboard_settings first, and use other update tools for language or model routing switches. The alternatives and selection conditions are 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 readOnlyHint=true, and the description adds real context beyond that: it names the data sources (skill registry and receipt store), restates non-mutation, and discloses the degraded-state contract of returning measured=False with an explicit reason when the store is absent or unreadable. That failure-mode disclosure is the valuable part, though it says nothing about result freshness or 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?

Three sentences, front-loaded with the read-only guarantee and the core purpose, then routing guidance, then the degraded-state caveat. Every sentence carries distinct information and nothing is repeated from the annotations or 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?

With an output schema present the description needn't explain return values, and with zero parameters there is no schema gap to fill. The description covers purpose, routing, data sources, mutation safety, and the failure contract, which is everything an agent needs 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 takes zero parameters, so the schema imposes nothing an agent must interpret and there is no parameter semantics to add. Baseline of 4 applies for a well-formed no-argument view.

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 ('return') plus the exact resources reported (skill lifecycle counts, selection/injection coverage) and scopes it to the active repository. The READ-ONLY prefix and the explicit contrast with dashboard_settings (feature switches) and dashboard_snapshot (task queue state) let an agent distinguish it from siblings without opening the schema.

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

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

Gives a concrete use case ('audit active skill reachability, selection receipts, and consecutive empty-injection streaks') and names two alternatives with the conditions that select them. No inference is required to route between this and the sibling dashboard views.

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 readOnlyHint annotation already signals safety, but the description adds useful behavioral context: it reads canonical SQLite state and cached storage telemetry, and it does not mutate tasks or launch processes. It does not discuss performance characteristics or caching behavior beyond the data sources, but the safety boundary is clearly reinforced.

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 READ-ONLY constraint, then gives mode guidance and alternatives in three efficient sentences. Every sentence contributes either scope, routing, or behavioral context with no 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?

Given the available output schema, full parameter descriptions, and read-only annotation, the description supplies enough context to select and invoke the tool correctly. It covers purpose, mode selection, alternatives, data sources, and non-mutation behavior without needing to duplicate return-value details.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful use-case semantics for the full parameter by contrasting compact manager summaries/status counts with the full native Webview payload, though it does not elaborate on the previous/previous_snapshot or known_contract_sha256 parameters beyond the schema.

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

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

The description uses a specific verb and resource: it builds the canonical dashboard queue, health, and storage snapshot for the active repository. It also distinguishes itself from related tools like dashboard_health and dashboard_task_detail, so an agent can select it without inspecting 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 states when to use the default compact mode versus full=True, including the intended use case for each. It also names alternatives for a cheap connection check and for a single task card, making the routing decision clear.

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

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

With no annotations, the description carries the full burden and does well: it discloses optimistic locking against expected_revision, atomic rewrite of the ignore policy file, and the side effect of triggering an immediate Source Graph refresh when the feature is enabled. It stops short of stating permission requirements or whether a failed revision check leaves the file untouched beyond 'fail closed' in the schema, so not quite 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?

Front-loads the verb and resource in the first line, then follows with usage routing and behavioral guarantees. Dense but every clause carries information; the single long final sentence with three comma-joined guarantees is slightly harder to scan than it could be.

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

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

Two required parameters at full schema coverage, an output schema handling return values, and a description that covers purpose, alternatives, locking semantics, and the refresh side effect. An agent has everything needed to call this correctly.

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

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

Schema coverage is 100%, so baseline is 3; the description adds genuine meaning by framing expected_revision as an optimistic-locking guard and clarifying that language_changes targets the ignore policy. It doesn't add syntax detail for the language ID keys, which remains in the nested schema description.

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

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

States a specific verb (atomically update), a specific resource (per-language Source Graph indexing switches), and scope (active repository). The 'USER WRITE' prefix immediately signals the operation class, and an agent can distinguish this from the settings/feature-switch siblings without opening any schema.

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

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

Explicitly names when to use this ('enable or disable individual languages in the Source Graph ignore policy') and routes to the correct alternatives: aiworkhub_dashboard_settings to read the current policy and revision first, and aiworkhub_dashboard_settings_update to toggle the top-level feature switch. When-to-use, prerequisites, and alternatives are all covered.

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

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

Annotations declare destructiveHint=true, and the description goes well beyond them: it names the exact effects (removes the batch directory, records an audit event, invalidates storage telemetry), the confirm=True gate, and the auth/deadline requirement. Nothing about the write's blast radius is left implicit.

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, both earning their place: the destructive warning and scope are front-loaded, then the prerequisite alternatives and side effects follow. No filler or 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?

For an irreversible mutation with an output schema already present, the description covers the safety profile, prerequisites, recovery path, and post-conditions. An agent has everything needed to call it correctly or avoid calling it.

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

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

Schema coverage is 100% and both parameters are documented in-schema, so the baseline is met. The description still adds meaningful state semantics — that the batch must be expired, authenticated, and past its restore deadline — which the schema's one-line param docs do not convey.

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

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

States a specific verb ('permanently delete') and a precisely scoped resource ('one expired worker-worktree quarantine batch from disk'), distinguishing it from the sibling preview, restore, and quarantine tools by its irreversible nature.

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: inspect with aiworkhub_dashboard_storage_retention_preview first, or use aiworkhub_dashboard_storage_restore while the undo window is active. It also states the precondition that the restore deadline must have passed, making the use condition unambiguous.

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

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

With no annotations, the description carries the full burden and does it well: it declares this is a write, that the move is reversible with an undo deadline, that a signed batch is created, that an audit entry is written, and that cached storage telemetry is invalidated. It also notes fail-closed behavior on a stale digest via the requirement for an unchanged preview_digest.

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 reversibility, then the prerequisite and alternatives — good ordering. The 'USER WRITE:' prefix and dense second sentence pack several facts together, which is efficient but slightly compressed.

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

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

An output schema exists, so return values needn't be explained; what remains — preconditions, reversibility, side effects (audit entry, cache invalidation), and the recovery path — is all present. Nothing an agent needs in order to call it safely 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 both parameters are already documented with defaults and the fail-closed stale-digest rule. The description's repetition of 'requires confirm=True and an unchanged preview_digest' restates the schema rather than adding new semantics, 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 ('move ... worktrees ... into a reversible quarantine batch') plus the scope constraint ('matching a current preview'). It is clearly distinguishable from the sibling preview/restore/purge tools and from the terminal-log and task quarantine variants.

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 prerequisite tool (storage_retention_preview to obtain preview_digest) and the alternative paths (restore to undo, purge to delete an expired batch). When-to-use and when-to-use-something-else are both spelled out.

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?

No annotations are provided, so the description carries the full behavioral burden. It discloses that the tool is a USER WRITE, refuses when foreign stale registrations exist or the digest drifted, runs git worktree prune, records an audit entry, and invalidates storage telemetry — exactly the behavioral context an agent needs for a mutating storage operation.

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

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

Two tight sentences, front-loaded with the action and scope, followed by prerequisites, alternatives, and refusal conditions. Every clause earns its place by adding an operational constraint or destination tool.

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

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

Given a mutating storage tool with no annotations but a full output schema, the description covers the required prerequisite, confirmation gate, refusal conditions, side effects, and alternative tool. It is complete enough for an agent to act safely without needing the output schema to explain 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%, so the parameter semantics are already well documented in structured fields. The description reinforces that preview_digest comes from the preview tool and that confirm must be True, but it does not add syntax, 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: pruning stale AIWorkHub Git worktree registrations. It adds the key qualifier that pruning is verified against a current preview digest, and explicitly distinguishes the action from physical directory quarantine.

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 instructs the agent to call aiworkhub_dashboard_storage_retention_preview first to obtain the digest, and names aiworkhub_dashboard_storage_quarantine as the alternative for moving physical worktree directories. It also states the confirm=True requirement, leaving little ambiguity about when and how to invoke 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?

With no annotations, the description carries the full burden and does so: it declares the confirm=True gate, that existing paths are not overwritten, that Git worktree registrations are reinstated, that the batch manifest and audit log are updated, and that storage telemetry is invalidated. These are non-obvious side effects an agent could not infer from 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?

The lead sentence front-loads the operation, and the following sentence packs the routing rule and side effects without filler. The second sentence is dense with several clauses, but each clause carries information an agent needs.

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

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

An output schema exists, so return values need not be explained. Given the absence of annotations and the mutation's complexity, the description covers the safety gate, collision behavior, registration handling, and bookkeeping updates – enough for an agent to call it correctly.

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

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

Schema coverage is 100%, so both parameters are already documented in the schema. The description restates the confirm=True requirement and implies batch_id identifies the quarantine batch, adding no format, ID-shape, or sourcing detail beyond the structured fields – 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 with scope: 'restore a quarantined worker-worktree batch back to the repository worktree root'. It also distinguishes itself from the two nearest siblings, retention_preview and purge, by 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?

Explicitly says to use it 'to roll back a quarantine batch listed by aiworkhub_dashboard_storage_retention_preview' and to use 'aiworkhub_dashboard_storage_purge to permanently delete an expired batch instead'. Both the when and the when-not are given with the alternative named.

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

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

Annotations already declare readOnlyHint=true, and the description reinforces it by stating it scans without moving or deleting files, plus it discloses the side-effect-free preview_digest artifact expected by downstream tools. Return shape is covered by the output schema, so this is close to complete.

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, each earning its place: the first states scope and read-only nature, the second routes to correct downstream and alternative tools. Front-loaded with the key scoping 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?

With annotations carrying the safety profile and an output schema covering return values, the description supplies the remaining needed context: what is scanned, that it is non-destructive, and how to sequence it before the mutation tools.

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

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

Only one parameter with 100% schema description coverage, so the schema already fully documents include_items and the description adds nothing about it. 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 (preview) plus three concrete resources (worker worktrees, stale Git registrations, storage quarantine batches), and the READ-ONLY framing plus scoping distinguishes it clearly from sibling mutation tools like storage_quarantine and storage_registration_prune.

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 this first to obtain a fresh preview_digest before the two downstream mutation tools, and names the alternative previews (terminal_log_retention_preview, task_retention_preview) for other resource types. Both when-to-use and when-not-to-use are covered.

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