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

Annotations already declare destructiveHint=true, idempotentHint=false, readOnlyHint=false, so the safety profile is covered. The description adds one genuinely useful behavioral fact — that link_number is auto-incremented — but says nothing about ordering constraints, required chain state (e.g. paused vs active), or that repeated calls create distinct links (non-idempotent).

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

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

Two short sentences, front-loaded with the action and followed by the one non-obvious side effect. No filler. Its brevity is the only reason it reads well; the content gap is a separate dimension.

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 annotations carry the safety profile. Still, for a destructive, non-idempotent mutation on a chain, the description omits prerequisite chain state and the effect on sibling links — leaving the agent to guess at operational context.

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

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

The description mentions only link_number, which is not an input parameter at all; chain_id, session_type, started, and progress_markers are unaddressed in prose. The schema descriptions do carry per-field text, but with reported 0% coverage alignment the description should be compensating and is not.

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 ("Add a new session link to a chain"), which is far more informative than the bare name. It distinguishes itself from complete_chain_link and branch_chain by implication, though it never names a sibling or clarifies what a 'session link' has to do with the surrounding chain vocabulary.

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

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

No guidance on when to add a link versus completing, branching, or spawning a child chain — all adjacent sibling operations. The agent has to infer usage entirely from the tool name and the one-line purpose statement.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is covered. The description adds only the vague phrase 'with retention metadata', which is not backed by any parameter and does not explain irreversibility, permissions required, or what happens to the archived chain — thin value for a destructive 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?

A single short sentence with the action front-loaded and no filler. The trailing 'with retention metadata' clause is vague and arguably unearned, keeping it from a 5.

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

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

For a destructive, irreversible-in-spirit archive operation with an undocumented parameter, the description omits prerequisites (must the chain be complete/closed?), effect on links and tickets, and what 'retention metadata' means. An output schema exists so return values need not be described, but the operational context is still insufficient.

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 reported at 0% and there is one required parameter (chain_id). The description says nothing about chain_id (format, valid values, or where to obtain it) and the mention of 'retention metadata' refers to no parameter at all, so it does not compensate for the coverage gap.

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

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

States a specific verb (move to archive) and resource (chain), plus a precondition ('completed chain'), so the agent knows what operation is performed. It does not, however, distinguish itself from nearby siblings such as complete_chain, set_chain_status, or update_chain_metadata, so the boundary is left implicit.

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

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

The phrase 'completed chain' implies a precondition for calling this tool, but the description never states when to use this versus complete_chain/close_ticket or what to do if the chain is not yet complete. Usage must be inferred.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=false, so the mutation profile is covered. The description usefully adds the lifecycle constraint that the parent chain will not complete until all branches finish, but says nothing about reversibility, permissions, or what gets created beyond the branch.

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

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

Two short, front-loaded sentences with no wasted words, stating the action first and the lifecycle consequence second. It is efficient though arguably under-elaborated for a destructive operation.

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 for a destructive mutation that forks a chain and blocks the parent's completion, the two-sentence description omits how branches are completed, whether siblings must all finish, and how to compose required fields like completion_vision and parent_chain_id.

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 mentions no parameters, and the top-level 'params' wrapper carries no description (reported coverage 0%). However, the nested schema does document each field (parent_chain_id, title, completion_vision, etc.), so meaning is conveyed structurally rather than by the prose; the description neither compensates nor is strictly required 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?

The description states a specific verb and resource ('Fork chain') plus a trigger ('when work splits'), making the action clear. It does not differentiate from siblings like spawn_child_chain or create_chain, so an agent cannot tell which branching tool applies without inspecting 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?

'when work splits' gives an implied usage condition, which is more than nothing. However, there is no explicit when-not guidance and no named alternative (spawn_child_chain, create_chain), leaving the routing 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?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered. The description adds one useful behavioral detail — operation independent of capacity_tracking — but does not explain detection logic, output format, or what 'stagnant' means beyond the schema's stale_days parameter.

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 core purpose, and the second sentence provides a useful operational constraint. No wasted words; appropriately sized for a simple check 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?

For a read-only, idempotent, one-parameter tool with an output schema and full annotation coverage, the description is nearly adequate. However, it does not help the agent choose between this tool and the close sibling 'check_stagnation', and it omits any guidance on interpreting the results or using stale_days.

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 provided schema description coverage is 0%, meaning the single parameter 'stale_days' lacks documented semantics in the structured data per the context signal. The description does not mention this parameter at all, so it fails to compensate for the coverage gap. Although the nested schema text contains a description for stale_days, the description itself adds no parameter meaning.

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 ('Detect') and resource ('stagnant/forgotten chains'), making the core purpose clear. However, it does not distinguish this tool from the sibling 'check_stagnation', leaving ambiguity about which check to use when.

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 only usage-related statement is 'Always active regardless of capacity_tracking', which tells the agent it can be used even without capacity tracking enabled. It does not say when to use this tool versus alternatives like check_stagnation, nor does it provide any exclusions or prerequisites.

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

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

Annotations already cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false), so the bar is lower. The description does add one behavioral fact beyond them: results are surfaced as observations rather than errors, which tells the agent how to interpret output. However, 'Design Principle 2' is unexplained internal jargon and no threshold values or scope limits are disclosed.

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

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

Front-loaded with the core action in the first sentence, followed by two compact definitions. The parenthetical '(Design Principle 2)' is unexplained filler, but overall it is short and efficient.

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-value explanation is not required, and the read-only/idempotent annotations cover safety. Still missing is the guidance an agent needs to choose this tool over its many siblings and any mention of the role parameter, leaving the definition minimally viable rather than complete.

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

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

Schema description coverage is reported at 0%, so the description is expected to compensate for the single 'role' parameter. It never mentions the parameter, the omit-to-check-all behavior, or acceptable role values, leaving parameter meaning to the schema alone.

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

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

States a specific verb+resource ('evaluate if any role has hit its stagnation threshold') and usefully defines the concept, distinguishing stagnation (engagement without growth) from dormancy (no engagement). It does not differentiate from adjacent siblings such as check_chain_health or get_dashboard, so it stops short of a 5.

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

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

No indication of when this tool should be reached for versus check_chain_health, get_dashboard, or read_capacity, and no exclusions or prerequisites are given. Usage must be inferred entirely from the tool name and concept definitions.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered structurally. The description adds one genuinely new fact — that closing flags an incomplete associated chain — but does not say whether that flag blocks the close, warns only, or is reversible, which matters for a destructive 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 short sentences, front-loaded with the action and followed by the advisory caveat. No filler, though it is arguably under-specified rather than optimally concise.

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

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

An output schema exists, so return values need not be explained, and annotations carry the safety profile. Still missing for a destructive lifecycle tool: whether a chain-incomplete close is blocked or merely flagged, required ticket state, and permission requirements.

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 reported at 0% for the single required parameter, so the description is expected to compensate — and it says nothing about ticket_id, its format, or where it comes from. With only one simple parameter the impact is limited, but the gap is real.

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 ("Close ticket"), which is unambiguous on its own. However it offers no differentiation from the many sibling ticket tools (read_ticket, update_ticket, promote_ticket, etc.), so an agent gets no help distinguishing this specific lifecycle 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?

There is no when-to-use guidance, no prerequisites, and no mention of alternatives such as promote_ticket or set_chain_status. The only context given is a behavioral note about the chain-incomplete flag, which is not usage routing.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds useful behavior beyond that: the pre-typed Build -> Review chain and the fact that chain creation is confirmed before proceeding. It does not explain the destructive nature or any side effects on the created chain links.

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

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

Front-loaded with the core action and only a few short sentences, all of which carry information. Somewhat fragmented phrasing ('Optionally creates chain' / 'Pre-typed: Build -> Review') costs a little readability 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?

An output schema exists, so return values need no explanation, and annotations cover the mutation safety profile. The gap is the undocumented 'entity' parameter and the lack of any statement about when this tool is preferred over its many sibling ticket-creation 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?

Schema description coverage is 0%, so the description must carry parameter meaning. It explains create_chain well, including its default-false behavior and consequence, but the 'entity' parameter is never mentioned anywhere, leaving a genuinely non-obvious parameter undocumented. Title and description are self-evident, so only partial compensation is achieved.

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: 'Create bug-fix ticket,' with the additional behavior of optionally creating a chain. It is clearer than the generic siblings (create_ticket, cmd_new_ticket) because it names the ticket type, but it never explicitly contrasts itself with 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?

Gives real guidance for the chain-creation branch ('Asks before creating chain via create_chain parameter. If false, ticket exists for tracking but no chain is created'), which is a when-to-use condition for that parameter. However, there is no guidance on when to pick this tool over create_ticket, cmd_new_ticket, or the other typed cmd_* siblings.

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

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

Annotations cover the safety profile (destructiveHint=true, idempotentHint=false, openWorldHint=false), so the description's added value is the multi-entity side effect: one call creates a ticket, a chain, and a planning declaration, and the chain starts in Planning. That composite-effect disclosure is genuinely useful and not derivable from the annotations. It stops short of saying whether failures leave partial state behind.

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

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

Front-loaded with the verb and the composite output, then the phase template. Four short lines, no filler; the trailing 'Starts in Planning' is slightly redundant with the phase list but harmless.

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 annotations carry the safety profile, but for a destructive, non-idempotent tool that creates three linked entities the description leaves the parameter meanings and the entity/vision relationship entirely unexplained. Adequate skeleton, real gaps.

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 three parameters (title, vision, entity), so the description carries the full burden and does not explain any of them. 'Planning declaration' and 'entity' are never connected, and the distinction between title and vision is left entirely to the caller's guess.

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 ('Create enhancement') and decomposes it into what actually gets produced: ticket + chain + planning declaration, plus the pre-typed phase sequence. This is materially clearer than a bare 'create' command and implicitly separates it from cmd_new_ticket/cmd_refactor, though it never names those siblings outright.

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 or when-not guidance: nothing tells the agent why it would pick cmd_enhancement over cmd_new_ticket, cmd_refactor, or cmd_bug_fix, or what preconditions the caller must satisfy. The only usage-relevant content is the resulting chain shape, which is inferred rather than stated.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is covered. The description usefully discloses the created structure (chain with a pre-typed six-stage funnel) and the initial stage, which goes beyond annotations. It does not state that the operation is irreversible or what permissions are needed.

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

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

Purpose is front-loaded in the first line, with the funnel detail following. The only minor waste is the redundant restatement that the funnel starts in Discovery immediately after listing Discovery first.

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. What remains missing is any explanation of the three parameters (especially entity) and the irreversible nature of creating a chain, leaving the definition adequate but with clear gaps.

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 description says nothing about title, entity, or vision. 'Title' and 'vision' are semi-self-evident, but 'entity' is opaque and is left entirely undocumented in both schema and description, so the description fails to compensate for the coverage gap.

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

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

States a specific verb and resource ('Create initiative') and then enumerates the composite output: ticket + full-funnel chain + discovery declaration. That is far more informative than the bare name. It does not, however, name which sibling it is not (e.g. cmd_new_ticket or create_chain), so differentiation is left to inference.

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 guidance and no mention of alternatives among the many create_* / cmd_new_* siblings. The note that it 'Starts in Discovery' hints at lifecycle context but never says what condition should lead an agent here rather than to cmd_new_ticket or create_chain.

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

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

Annotations already declare destructiveHint=true and non-idempotent, so the safety profile is covered. The description adds genuine behavioral context beyond that: a conditional return value (a chain-creation prompt when the type triggers the Lockstep threshold) and the fact that a Partner handles follow-up. It stops short of explaining what the 'Lockstep threshold' or 'Partner' actually are.

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?

Short and front-loaded: the core action leads, followed by the conditional behavior. Efficient overall, though the wrapped formatting and undefined jargon ('Lockstep', 'Partner') add a little noise.

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

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

An output schema exists, so return values need not be fully documented, and annotations cover the safety profile. However, for a 6-parameter mutation tool with zero schema description coverage, the near-total absence of parameter guidance leaves the definition incomplete for correct invocation.

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

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

Schema description coverage is 0% across 6 parameters, so the description must compensate and it barely does. It alludes to a 'ticket type' but never explains the type values, the meaning of entity, priority, or tags, nor how title/description/type relate.

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+resource ('Create a new ticket') and adds the qualifier 'Generic — human specifies everything,' which hints this is the raw command variant among the many specialized cmd_* siblings (cmd_bug_fix, cmd_refactor, etc.). It does not, however, distinguish itself from the plain create_ticket sibling, leaving the boundary ambiguous.

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

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

Usage is only implied. The description notes a conditional ('If the ticket type triggers Lockstep threshold (not maintenance)') but gives no guidance on when to prefer cmd_new_ticket over create_ticket or the specialized command variants, nor any prerequisites.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false, and readOnlyHint=false. The description adds genuinely non-redundant structural context — that creation spans a ticket plus a pre-typed chain starting in Architecture — but it never explains why this creation is flagged destructive or what side effects/state it introduces.

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

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

Four tight lines with no wasted prose; the core action is front-loaded and the workflow/scope notes follow. Minor inefficiency: the 'scope' definition is tacked on at the end rather than grouped with the parameters it describes.

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 annotations carry the safety profile. However, for a creation tool that also provisions a multi-stage chain, the description omits when-to-use-vs-alternatives and the meaning of the optional 'entity' param, leaving real gaps.

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. It clarifies the required 'scope' parameter ('what's being refactored and why?') but says nothing about 'title' or the optional 'entity' parameter, leaving two of three params undocumented 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?

The description states a specific action and composite resource: 'Create refactor: ticket + chain + architecture declaration.' This is clearer than a bare verb and distinguishes it as the refactor-workflow variant of the cmd_* family, though it never explicitly names a sibling (cmd_bug_fix, cmd_enhancement) 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?

It describes the internal chain (Architecture -> Build -> Review, starting in Architecture) but gives no guidance on when to choose this over the very similar cmd_new_ticket, cmd_enhancement, cmd_bug_fix, or create_chain siblings. Usage is left entirely to inference from the word 'refactor'.

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 idempotentHint=true, and the description goes further by disclosing concrete side effects: auto-closing the associated ticket for bug-fix/maintenance chains and an advisory-only closure suggestion for other chain types. This is meaningful behavioral context beyond the flags, though it omits whether the auto-close is reversible.

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 action is front-loaded in the first sentence and the bulleted lifecycle behavior is compact. The phrase 'Lifecycle hooks per Decision 1' burns space on an opaque internal reference an agent cannot resolve.

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

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

With an output schema present, return values need not be described, and annotations already carry the safety profile. The description covers the key side-effect branching, leaving only minor gaps such as what happens to chain links on completion.

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

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

There is a single parameter (chain_id) with 0% schema description coverage, and the description says nothing about it. Baseline 3 applies only when schema coverage is high; here the schema offers only 'Chain identifier' and the description does not compensate with format or sourcing guidance.

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

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

The description states a specific verb and resource ('Mark entire chain complete'), which clearly separates it from the sibling complete_chain_link. However, it does not explicitly contrast itself with archive_chain or set_chain_status, which are the nearest ambiguous alternatives, so sibling differentiation is only partial.

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

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

The description implies usage through the lifecycle-hook behavior (bug-fix/maintenance vs other chain types), but never states when to call this versus archive_chain, set_chain_status, or complete_chain_link. Context is implied rather than 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 declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is externally supplied. The description adds only the side effect of recording deliverables and says nothing about what completion destroys or mutates, whether it advances the chain to the next link, or what happens to the handoff file, which is exactly the gap a destructive, idempotent mutation should address.

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 compact sentence with the action and its side effect front-loaded and no filler. It is efficiently written, though its brevity is part of why the other dimensions are thin rather than a demonstration of disciplined scoping.

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 for a destructive, non-read-only lifecycle mutation with undocumented parameters and a large family of chain siblings, the description leaves critical context missing: which link is affected by default, what completion implies for the chain's subsequent state, and how deliverables/handoff interact.

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 nested input object holds five meaningful fields (handoff, chain_id, link_number, deliverables, progress_markers) with a top-level schema description coverage reported at 0%, so the schema is not carrying this load. The description mentions only deliverables and omits the link_number default behavior and the handoff/progress_markers semantics, so it fails to compensate for the coverage gap.

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

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

"Mark a chain link as complete, record deliverables" gives a specific verb (complete) and resource (chain link), plus a secondary effect (recording deliverables). It does not distinguish this from the closely named sibling complete_chain, which completes an entire chain rather than one link, leaving some ambiguity an agent must resolve by other means.

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

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

There is no statement of when to use this tool versus complete_chain, add_chain_link, or set_chain_status, and no prerequisites or ordering guidance for the chain lifecycle. The agent must infer the intended call context entirely from the name.

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

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

Annotations already declare destructiveHint=true and non-idempotent behavior, so the safety profile is covered. The description adds useful context that chain_id is generated from a kebab-case title, but it does not describe side effects, auth requirements, or what happens to the source ticket.

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

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

Two short sentences, front-loaded with the action and then the ID-generation detail. No filler or redundancy.

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

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

An output schema exists, so return values need not be explained, and annotations carry the destructive safety profile. However, for a creation tool with many optional fields and sibling alternatives, the description omits usage conditions, prerequisites, and the effect of optional parameters, leaving it minimal but not misleading.

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 nested schema already provides descriptions for all nine fields, so baseline 3 applies. The description adds only that the title is used in kebab-case to generate chain_id; optional fields like entity, chain_type, and expected_sequence are not mentioned in the description but are covered by the schema.

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

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

States a specific verb and resource ('Create a new chain'), scopes it to a ticket, and adds ID generation behavior. This clearly distinguishes it from sibling read, update, list, and lifecycle-chain tools.

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

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

No when-to-use guidance, alternatives, or prerequisites are given. The phrase 'from a ticket' implies a prerequisite but does not state that the ticket must exist or when to choose this over sibling tools like spawn_child_chain or cmd_new_ticket.

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

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

Annotations already declare the safety profile (readOnly=false, destructive=true, idempotent=false, openWorld=false), so the bar is lower. The description adds one useful behavioral fact — that the ID is auto-assigned sequentially — but says nothing about permissions, side effects, or what happens on failure.

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, front-loaded with the action and the one notable behavior. It is efficient but arguably under-specifies for a mutation 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?

An output schema exists, so return values need no explanation. However, for a non-idempotent, destructive create operation with zero schema description coverage and many sibling creation tools, the description omits the required inputs and any routing guidance.

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

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

Schema description coverage is reported at 0%, so the description must carry parameter meaning, and it adds none. It does not mention the required title/type fields, the priority default, or the tags/entity/description options.

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 (create) and resource (ticket), plus a distinguishing behavioral detail (auto-assigned sequential ID). It does not, however, differentiate itself from the several sibling creation tools (cmd_new_ticket, cmd_bug_fix, create_chain), so an agent still has to infer 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?

No when-to-use guidance is given. With siblings like cmd_new_ticket, cmd_new_initiative, and cmd_bug_fix, the agent gets no signal about when this generic create_ticket is preferred over the specialized commands.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered. The description adds nothing beyond that: no pagination behavior, no ordering of results, no statement of what 'history' means in scope. With annotations doing all the work, the description contributes no extra behavioral context.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though the brevity border on under-specification for a tool with a required parameter and several filters.

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 annotations cover the safety profile. Still missing for correct invocation: that 'role' is required, how far back history goes, and whether results are ordered or capped at the default limit.

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

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

With schema description coverage reported at 0% for the top-level params wrapper, the description should carry the burden but only offers 'optional filters'. It says nothing about the required 'role' argument, the limit default of 50, the date format of 'since', or the enum values for event_type.

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 ('Query') and resource ('capacity event history'), which is enough to distinguish it from the sibling record_capacity_event. However, it never names that write-side sibling or contrasts read vs. write, so the differentiation is implicit 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?

'with optional filters' hints at how to narrow results but gives no when-to-use condition, no exclusion, and no pointer to the read_capacity sibling that an agent might otherwise confuse this with. The agent gets no routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds that the call is lightweight and what fields it reports, which is modest extra context but says nothing about cost, pagination, or failure modes.

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

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

A single front-loaded fragment with no filler words; the essential content (status fields returned) leads. It is efficient, though arguably so terse that it crosses into under-specification rather than pure conciseness.

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 needn't be spelled out, and safety is covered by annotations. What is missing is the routing information an agent needs: why this lightweight check rather than read_chain or check_chain_health, and any semantics for chain_id.

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 (chain_id) with schema description coverage at 0% – the schema gives just 'Chain identifier' with no format, accepted values, or scope. The description does not compensate at all, so the agent gets no guidance on what a valid chain identifier looks like.

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

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

States the resource (chain status) and enumerates exactly what it returns: current link, phase, and health. It is clear what the tool surfaces, but it offers no differentiation from close siblings like read_chain or check_chain_health, leaving the agent to guess which status-oriented tool applies.

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 'lightweight' hints at a preference for this over heavier reads, but there is no explicit when-to-use statement, no prerequisites, and no named alternative among read_chain, check_chain_health, or search_chains.

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

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

Annotations already declare readOnlyHint, idempotentHint, and a closed-world scope, so the safety profile carries no burden here. The description adds that this is a single-call aggregate spanning four data domains, which is useful context, but says nothing about size, freshness, or truncation behavior of the aggregate.

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 content summary front-loaded and the usage rule second. The 'Aggregate view:' fragment is slightly terse but every clause carries information; no 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?

An output schema exists, so return values need not be described. The description covers what data domains are included and the intended call position, which is adequate for a 1-parameter read tool; only the entity filter's meaning is left 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 description coverage is reported at 0%, so the description is expected to compensate and does not: the optional 'entity' filter is never mentioned. The only hint of filtering is absent entirely, leaving the agent to discover the scoping parameter from the schema alone.

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

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

The description names the resource (dashboard) and enumerates its contents: active chains, open tickets, capacity summary, alerts. That aggregation scope is specific enough to distinguish it from the granular siblings (list_chains, list_tickets, read_capacity), though no sibling is named explicitly.

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

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

It gives an explicit call-ordering rule: 'First tool called every session.' That is real usage guidance an agent can act on. It lacks any when-not condition or named alternative for narrower queries, which keeps it out of 5 territory.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, which covers the safety profile. The description adds genuinely useful behavior — that a differing ticket becomes a child_ticket when an origin exists — but never explains what a destructive link operation changes or what a 'wrong' link does to the chain.

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?

Short and front-loaded: the core action leads, followed by the conditional child_ticket rule. No filler sentences, though the '(Decision 2)' reference is opaque without external context.

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

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

An output schema exists so return values need not be described, and annotations cover safety. But for a destructive, idempotent mutation tool the missing usage/alternative guidance and param clarification leave it only minimally complete.

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

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

Schema description coverage is 0% and the single nested params object hides chain_id/ticket_id. The description only implicitly references ticket_id via the origin-ticket sentence and never clarifies chain_id or how the two interact, so it does not compensate for the coverage gap.

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

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

States a specific verb and resource: 'Associate a ticket with a chain.' The second sentence explains the origin/child logic, which sharpens what the operation does. However, it does not distinguish this tool from the closely related sibling add_chain_link, leaving ambiguity about which linking tool to pick.

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-tool guidance. Given the many nearby siblings (add_chain_link, complete_chain_link, create_chain, branch_chain), the agent gets no routing help.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive, and closed-world, covering the safety profile. The description adds the 'active' filter and 'lightweight summary view' behavior, which is useful context. However, it doesn't describe return shape or filtering beyond 'active'. With annotations covering safety, a 3 is appropriate.

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?

Single short sentence with zero waste, front-loading the verb and resource plus the key qualifier.

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. For a parameterless list tool with full annotation coverage, the description is nearly complete; only routing guidance against the many sibling chain readers 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?

No meaningful parameters (schema is an empty object wrapper). Baseline for 0 params is 4. The description's 'active' qualifier implicitly defines the scope, though no parameters exist to document.

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?

Clear verb+resource: 'List all active chains.' The parenthetical '(lightweight summary view)' distinguishes it from read_chain and get_chain_status by describing the view type, though it doesn't explicitly 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?

No when-to-use or when-not-to-use guidance. The description doesn't say when to call list_chains vs search_chains vs read_chain, despite many chain-reading siblings existing. Only implied by 'active' scoping.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, and openWorldHint=false, so the safety profile is covered structurally. The description adds one useful behavioral detail, that the result set is scoped to open tickets, but says nothing about ordering, pagination, or result size.

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

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

A single front-loaded sentence with no wasted words. It is efficient, though arguably so terse that it omits scope information the agent might need.

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 is simple and has an output schema, so return values needn't be explained. Still, for a list operation the description omits ordering, pagination, and result-count behavior, leaving the agent without enough to anticipate output volume.

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 effectively takes no meaningful input (a single empty params object), so there are no parameters whose semantics need explanation. Per the baseline for zero-parameter tools, a 4 is appropriate; the 0% schema coverage is moot given the empty schema.

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

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

States a clear verb (List) and resource (tickets) with a scope qualifier (open), so the operation is identifiable. However, it does not differentiate itself from sibling search_tickets or the create/read/update ticket tools, leaving ambiguity about when listing is preferable.

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

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

No guidance on when to use this versus search_tickets, read_ticket, or other ticket siblings. The 'open' qualifier implies a filter but no context or exclusions 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?

'Idempotent' merely restates the idempotentHint annotation, but 'preserves state, signals not abandoned' adds semantic context about the effect of the call. It does not explain the destructiveHint=true annotation or what exactly changes, so the addition is partial.

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, front-loaded fragment with no filler; the key semantics come first. It is tight, though terse enough to leave meaning implicit.

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?

In a 40+ sibling lifecycle ecosystem, an agent needs to know how pause differs from archive_chain, complete_chain, and set_chain_status. With no output-schema burden (output schema exists), the description could have used that space for lifecycle routing but does 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% for the single required parameter chain_id, and the description offers nothing about its expected format, source, or constraints. The description must compensate here and does not.

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 ('Pause chain') that an agent can immediately contrast with resume_chain and the other chain-lifecycle siblings. No sibling is named explicitly, but the operation is unambiguous.

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

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

'signals "not abandoned"' hints at the intent behind pausing (versus closing/archiving), which is real guidance. However, it never says when to choose pause_chain over archive_chain, complete_chain, or set_chain_status, nor states prerequisites.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and readOnlyHint=false, so the safety profile is covered. The description adds the workflow (chain creation, related-ticket scan, candidate return, optional immediate nesting), but does not disclose what 'destructive' actually means here – whether the original ticket survives, whether promotion is reversible, or what permissions are required.

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

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

Purpose is front-loaded in the first sentence and the rest is efficient multi-line prose with little waste. The unexplained '(Decision 1)' reference is the one piece that does not earn its place.

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

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

An output schema exists, so return values need not be explained. However, for a destructive mutation tool, the description leaves gaps on prerequisites, side effects on the source ticket, and the required completion_vision input – enough to be usable but not fully complete.

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

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

Reported schema coverage is 0%, so the description must carry the burden, yet it only loosely maps to nest_tickets ('nest specified tickets immediately') and never mentions the required completion_vision parameter. The visible schema does describe each field, which props this up to an adequate 3, but the description contributes little parameter-level meaning.

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 ('Promote a standalone ticket into a chain') and explains the mechanism (creates a chain, scans for related tickets, returns nesting candidates). It is clear enough to distinguish from generic create_chain/create_ticket. It does not, however, explicitly contrast itself against those siblings, and the unexplained '(Decision 1)' jargon adds noise.

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

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

Usage is only implied: the agent can infer this applies when a standalone ticket should become a chain, and nesting is optional ('Optionally nests specified tickets immediately'). There is no explicit when-to-use, when-not-to-use, or named alternative (e.g. create_chain) 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, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is fully covered by structured data. The description adds nothing beyond restating the read scope, so it neither enriches nor contradicts the annotations.

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

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

One short sentence, front-loaded with the verb and resource; nothing is wasted. It is perhaps too terse given the ambiguous "capacity" vs "growth stage" terminology, but structure is clean.

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 annotations cover the read-only/idempotent profile. However, the description never clarifies what a "growth stage" contains or how capacity state relates to the sibling capacity-event tools, leaving a small gap for this tool's role in the family.

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 mirrors the schema's own role semantics (specific role vs. all roles) but adds no extra meaning such as accepted role strings, casing, or behavior for an unknown role. With a single low-complexity parameter this is adequate but not additive.

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

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

The description gives a clear verb ("Read") and resource ("growth stage" / capacity) scoped by role or all roles. It is understandable on its own, though it doesn't explicitly differentiate itself from nearby siblings like get_capacity_events or check_stagnation, which also surface capacity-related state.

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?

"for a specific role or all roles" implies the two usage modes but never states when to prefer this tool over update_capacity_stage or get_capacity_events. The guidance is inferable from the parameters rather than spelled out as an explicit when/when-not rule.

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

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

Annotations already cover read-only, idempotent, non-destructive behavior. The description adds meaningful output-shaping context: early-phase chains return fewer fields to reduce cognitive load, and full data requires a different access path. It does not explain which fields are omitted or how phases are determined.

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

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

Two short sentences, front-loaded with the core action and followed by a useful behavioral note. There is no filler, and every sentence earns its place.

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

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

With an output schema present and annotations covering safety, the description need not detail return values. It adds the key progressive-disclosure caveat, though it could more explicitly distinguish this tool from other chain-reading siblings.

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 provides no information about the sole parameter, chain_id. Although the schema includes a minimal 'Chain identifier to read' description, the reported schema description coverage is 0%, so the description should compensate and does not.

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 (Read) and resource (chain state), and the progressive-disclosure qualifier distinguishes it from plain chain reads. It does not explicitly name sibling alternatives, so it falls short of full sibling differentiation.

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

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

The description implies usage through 'progressive disclosure' and notes that full data is available via direct YAML read, which hints at when this filtered view is appropriate. However, it gives no explicit when/when-not guidance relative to sibling tools such as get_chain_status or list_chains.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is fully covered elsewhere. The one added signal is 'full ... state', implying a complete rather than partial read, but there is no mention of auth requirements, error behavior on unknown IDs, or pagination.

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 zero filler. It is efficient, though the brevity comes at the cost of the missing usage and parameter detail noted elsewhere rather than through disciplined pruning.

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, the description needn't document return values, and the annotations cover the safety profile. Still, for a tool with 39 siblings it omits the routing information that would let an agent distinguish it from list_tickets or read_chain.

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 reported as 0%, so the description needs to carry parameter meaning and it does not — it never mentions ticket_id, its format, or the TICKET-002 convention. It adds nothing beyond the schema's own single field.

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 (Read) and resource (ticket) plus the scope qualifier 'full ... state', which signals a complete single-ticket fetch as opposed to a summary. It never names or distinguishes itself from close-by siblings like read_chain or list_tickets, so an agent must infer the ticket-vs-chain boundary.

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

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

The description gives no when-to-use guidance and no exclusions. It does not say to use read_ticket rather than list_tickets or search_tickets when you have a known ticket_id, leaving the agent to infer the selection rule.

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

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

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=true, idempotentHint=false), so the description need not restate it. What it fails to add is any of the context annotations cannot convey: what 'destructive' means here, whether events are append-only, validation rules on the enum attribution, or how entries relate to a chain/role.

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 key qualifier ('typed attribution') appears early. It is efficient, though its brevity is partly the source of the missing guidance rather than a virtue.

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 a five-value attribution enum whose semantics (partner_performed vs human_performed vs human_corrected) materially affect correct invocation, the description offers no decision support. An output schema exists so return values need not be explained, but the input-side context is too thin.

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 reported at 0% and the description only gestures at 'typed attribution', which duplicates the event_type enum already visible in the schema. It adds no meaning for role, chain_id, or the free-text description field, so it does not compensate for the coverage gap.

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

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

States a specific verb ('Log') and resource ('capacity-relevant event'), which distinguishes it from read-side siblings like get_capacity_events and from other recorders like record_catch_event and record_gate_skip. However, 'capacity-relevant' is left undefined, so the agent must infer the domain boundary from the enum rather than the prose.

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

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

No guidance on when to log a capacity event versus using record_catch_event, record_gate_skip, update_capacity_stage, or get_capacity_events. The description never states the triggering condition or any prerequisite (e.g., an existing chain/role).

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

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

Annotations already declare a non-read-only, non-idempotent, destructive write, so the agent knows the safety profile. The description adds only that human_reasoning is 'optional but gold when present' and offers no disclosure of what the destructiveHint implies here, whether records can be amended, or what the call returns. Given it labels itself 'log', a reader might reasonably assume append-only safety, which the destructive annotation undercuts—so the prose undersells the annotation rather than reinforcing it.

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

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

Front-loaded with the action and appropriately short, but two of the four sentences are rhetorical framing ('system working, not failure', 'whether catches lead to better decisions') that consume space without helping an agent call the tool correctly.

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 annotations cover the safety profile. But for a tool with a 7-field enum-driven event payload, the description never situates the call in a workflow or clarifies the jargon it depends on, leaving an agent without enough to decide when this event should be recorded.

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?

Top-level schema coverage is reported at 0%, but the single top-level param is a nested object whose properties each carry their own schema descriptions (triggers, actions, assessments). The description's only parameter contribution is the note that human_reasoning is optional and high-value, which is genuinely additive but does not compensate for the coverage gap elsewhere.

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 (Log) and a resource (Catch firing), and the enum values in the schema imply a structured event record. However, 'Catch firing' is opaque domain jargon with no gloss, and the description does nothing to distinguish this tool from the many sibling 'record_*' tools (record_handoff, record_gate_skip, record_session_declaration).

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 guidance, no prerequisites, and no named alternatives. The sentences about catches being 'system working, not failure' are motivational framing rather than operational conditions for invoking the tool.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, and idempotentHint=false, so the agent knows this is a mutating write. The description adds useful context beyond the annotations – that the skip is recorded for pattern detection over time and that this is a non-blocking log rather than an enforcement action. It still omits permissions, reversibility, and what 'destructive' actually means 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?

The description is short and front-loads the action, but the parenthetical '(Design Principle 1)' is internal jargon that consumes space without helping the agent, and the awkward line breaks fragment two otherwise distinct ideas. Adequate but not 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?

With an output schema present, return values need not be described, and the nested input type is well documented. For a mutating tool with destructiveHint=true, though, the description never explains the side effects, idempotency behavior, or error conditions, which leaves gaps an agent cannot fill from structured data 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?

Top-level schema coverage is 0%, but the single 'params' object references a $defs type whose five required fields (chain_id, skipped_from, skipped_to, reason, partner_assessment) each carry their own descriptions, so the schema does the heavy lifting. The description adds nothing about parameters, which is acceptable given the nested documentation but earns no credit.

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 verb ('Log') and a resource ('session-type leapfrog in chain metadata'), and the schema fields clarify that this records a skipped session type. However, the terminology is opaque ('leapfrog', 'Design Principle 1') and it does not distinguish this tool from any sibling. The purpose is inferable but not stated crisply.

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

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

The line 'Partner flags, explains cost, asks — never refuses' describes conversational flow rather than when to call the tool. There is no condition for use, no prerequisite, and no reference to any alternative tool. An agent must infer that this is called after a human declines an expected session type.

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

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

Annotations already declare readOnlyHint=false (write) and destructiveHint=true, so the description's 'Write' phrasing is consistent and adds the destination target (chain link and data directory). However, it does not explain what the destructiveHint means here — whether existing handoff data is overwritten, what a chain link write implies, or the idempotency behavior that idempotentHint=true promises. With annotations carrying the safety profile, a 3 is appropriate.

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

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

Two short sentences, front-loaded with the action and target before the payload enumeration. No filler or redundancy; only minor room to tighten phrasing.

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 and annotations are present, so return values and safety hints need not be restated. Still, for a destructive write into a chain-of-handoffs workflow, the description omits what happens to existing handoff data and how it relates to the surrounding chain tools, leaving a moderate gap.

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

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

Reported top-level schema coverage is 0% because the single 'params' wrapper is undocumented, but the nested RecordHandoffInput properties carry rich descriptions in the schema. The description's list of captured content loosely maps to those nested fields (decisions, files changed, open threads, next-session recommendation) without adding format or cardinality details beyond the schema, so baseline 3 is correct.

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

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

The description names a specific verb (Write), resource (session-end handoff) and destination (chain link and data directory), then enumerates the captured payload (decisions, files changed, open threads, emotional context, next-session recommendation). This is clear enough to distinguish it from generic record_* siblings, though it never names an alternative tool explicitly.

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

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

The phrase 'session-end handoff' implies the timing (end of session), which gives some usage signal, but there is no explicit when-to-use guidance, no prerequisites, and no reference to a related sibling such as add_chain_link or complete_chain_link. Usage is inferred rather than stated.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, and idempotentHint=true, so the safety profile is covered. The description adds nothing about what a write does to the chain link, whether prior declarations are overwritten, or permission requirements.

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

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

Two short sentences, front-loaded with the core action and followed by a component list. Minor waste in the multi-line formatting but no filler prose.

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

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

An output schema exists and annotations cover the safety profile, but for a destructive, idempotent write to a chain link the description never explains the chain-link model, what happens on re-invocation, or the meaning of the declaration in the workflow. It is too thin for the tool's role.

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 lists components (type, goal, deliverable, completion criteria, out of scope, partner confirm) that partially map to the schema fields, but 'partner confirm' matches no property and 'context_from_previous' is omitted. The schema itself already carries per-field descriptions, so the prose adds little and is slightly out of sync.

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 ('Write Session Declaration') and names the target container ('current chain link'), which differentiates it from siblings like record_handoff or record_gate_skip. It stops short of fully disambiguating from other record_* tools, but an agent can identify the operation.

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, no prerequisites, and no mention of alternatives among the many record_*/chain tools. The agent must infer that this is called at session start from the word 'Declaration' alone.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, so the safety profile is known. The description adds real value beyond that by disclosing blast radius — the chain file, ticket references, declaration files, handoff files, catch files, and parent/child chain references are all rewritten. It does not state reversibility or failure behavior on conflicts, 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?

The lead sentence is front-loaded and complete; the following multi-line list of affected files is informative but somewhat padded by line breaks rather than prose. No egregious 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?

An output schema exists, so return values need not be described, and annotations carry the safety profile. For a destructive rename that rewrites references across many artifacts, the description covers what is touched but omits what happens on partial failure or whether the operation can be undone.

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?

Reported schema description coverage is 0%, and the description contributes nothing about the parameters — it never mentions chain_id, new_title, or the kebab-case conversion of the title. The description therefore fails to compensate for the coverage gap, leaving parameter meaning to the raw schema only.

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 ('Rename a chain') and then enumerates the concrete effects (updates chain_id, renames YAML file, fixes cross-references). This clearly separates it from siblings like update_chain_metadata or create_chain. It stops short of explicitly naming that sibling distinction, so it is not a 5.

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

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

Usage is implied by the name and the description — you rename a chain when its title/identifier must change. However, there is no explicit guidance on when to prefer this over update_chain_metadata (which also mutates chain metadata) or any prerequisite/exclusion statements. Implied usage only.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the safety profile is largely covered. The description adds one genuinely useful behavioral fact not in annotations — the required prior state — but says nothing about side effects of resuming (e.g., whether paused work re-executes), which matters given the destructive hint.

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

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

Two short sentences, zero filler, with the action front-loaded and the constraint immediately following. Nothing could be cut without losing meaning.

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

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

With an output schema present, return values need no explanation. The description covers the action and its state precondition, which is sufficient for a single-param state transition, though it leaves the destructive semantics of resuming 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?

There is a single required parameter (chain_id) with 0% description coverage in the metric, and the description does not mention it at all. However, the schema's own field description ('Chain identifier') and the low parameter count make this a minimal-risk gap, so the baseline for a near-trivial param set 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 ('Resume a paused chain'), which clearly distinguishes it from pause_chain, complete_chain, and archive_chain in the sibling list. It does not explicitly name a sibling alternative, but the operation itself is unambiguous.

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

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

'Only valid from paused state' gives an explicit precondition for use, which is the key gating rule for this state-transition tool. It stops short of naming alternatives (e.g., what to call instead when the chain is not paused), so it is clear context rather than full 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so safety is covered. The description adds no behavioral context beyond that — nothing about result limits, pagination, whether filters combine with AND, or whether matching is exact or substring. With annotations doing the heavy lifting, a low addition score is warranted.

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 no redundancy. It is efficient, though its terseness borders on under-specification for a tool with several sibling alternatives.

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 a read-only search tool sitting alongside list_chains and search_tickets needs at minimum a disambiguation sentence and filter-combination semantics; both are missing, leaving the definition materially incomplete for selection purposes.

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 reported at 0% for the top-level 'params' wrapper, and the description merely recites the same filter names that appear in the schema (entity, status, session type, date range). It supplies no matching semantics, no defaults, and no guidance on date format or combinability, so it fails to compensate for the coverage gap.

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

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

The description gives a specific verb ('Search') and resource ('chains') plus the filter dimensions, so an agent knows exactly what the tool returns. However, it does nothing to distinguish it from the sibling list_chains, leaving the agent to guess which of the two to call when no filters are needed.

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

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

There is no statement of when to use this tool versus list_chains or the other 40+ siblings. No exclusions, no prerequisite conditions, and no hint about what happens when all filters are omitted (return everything? error?). The agent must infer everything from the name.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true and destructiveHint=false, so safety is covered externally. The description adds nothing beyond that - no note on pagination, result limits, filter combination semantics, or whether all params are optional.

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 compact sentence that leads with the verb and resource, with zero filler. It is arguably too terse for the guidance an agent needs, but nothing in it 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?

An output schema exists, so return values need not be described, and annotations cover the safety profile. What is missing for a search tool is whether filters AND together, the default result scope, and how it differs from list_tickets - gaps the annotations cannot fill.

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% because the real field docs sit inside $defs behind a params $ref, so the description's enumeration of type/entity/priority/status does useful compensation. It stops short of explaining values - no enum hints for type or priority, and no indication that every filter is optional/nullable.

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 (Search) and resource (tickets) plus the four filterable facets, so the operation is unambiguous. It does not, however, differentiate itself from the sibling list_tickets or search_chains, leaving the agent to infer which is appropriate.

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, no exclusions, and no mention of alternatives such as list_tickets for unfiltered retrieval or search_chains for chain-oriented queries. The agent gets no routing help.

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 idempotentHint=true, signaling this overwrites existing entity assignment and repeated calls yield the same result. The description does not disclose that it overwrites (potentially destructive), doesn't mention null-clearing behavior, and doesn't confirm idempotency. For a destructive mutation tool, the disclosure is thin. However, annotations cover the core safety profile, so behavioral overlap exists – but the description adds almost nothing beyond them.

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

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

Single concise sentence with no waste. Front-loads the action. Loses a point only because the parenthetical is ambiguous rather than clarifying.

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, idempotent, mutation tool with an output schema and zero top-level schema coverage, the description is too sparse. It omits overwrite semantics, null-clearing behavior, prerequisites, and error conditions. An agent lacks the context to invoke this confidently against siblings that also mutate chains.

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% at the top level, though the nested entity and chain_id have inline descriptions ('null = parent org', 'Chain identifier'). The outer 'params' wrapper is undocumented. The description's '(which subsidiary)' loosely mirrors the entity param semantics but adds no syntax, format, or validation details beyond what the inner schema provides. The low coverage means the description should compensate more than it does.

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 (tag) and resource (chain) with a qualifier about entity ownership, but the parenthetical '(which subsidiary)' is vague about whether this assigns, changes, or clears ownership. Among many sibling chain-mutation tools (rename_chain, set_chain_status, update_chain_metadata), the description doesn't clearly differentiate what set_chain_entity uniquely does versus updating metadata.

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

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

No guidance on when to use this vs alternatives like update_chain_metadata or tag_ticket. The description doesn't say if this replaces an existing entity, requires the chain to be in a certain state, or how it differs from other chain-mutation siblings. An agent cannot infer usage conditions from this sentence alone.

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

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

Annotations already declare destructiveHint=true, idempotentHint=true and readOnlyHint=false, so the safety profile is covered. The description adds one genuine behavioral fact beyond that — that transitions are validated — but it never states which transitions are legal, what happens on an invalid transition, or the consequences of terminal states like archived. For a destructive mutation, that is a meaningful 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?

One sentence, front-loaded with the verb and resource, with zero filler. It is efficient, though the brevity is part of the under-specification problem rather than pure conciseness.

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 for a destructive, state-machine-driven tool sitting among many single-purpose transition siblings, the description omits the transition rules, the terminal-state semantics, and the routing rationale — the exact information an agent needs before invoking 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?

Reported schema description coverage is 0%, so the description carries the burden and adds nothing: it names neither chain_id nor the status value set. The enum of valid statuses and the field meanings live only in the schema, and the description does not compensate for that thin coverage or explain the relationship between the two parameters.

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 ('Update chain status'), which is clearer than a tautology. However, it does not distinguish this tool from siblings that perform what look like subsets of the same operation (pause_chain, resume_chain, complete_chain, archive_chain), so an agent cannot tell why it would call the generic setter instead of a named transition.

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

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

There is no when-to-use guidance at all: no named alternatives, no conditions selecting this tool over the dedicated transition tools, and no preconditions. The only guidance is implied by the words 'state transition validation', which is not enough to route an agent.

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

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

Annotations already declare the mutation profile (destructive=true, idempotent=false, readOnly=false). The description adds genuine behavioral context beyond that: the parent retains its type and history, and the operation is explicitly 'fork, never morph'. It stops short of describing creation side effects or reversibility.

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, front-loaded with the action and its trigger. The '(Decision 5)' reference occupies space without helping an agent decide or call the tool, but nothing else 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?

An output schema exists, so return values need not be explained. The description covers trigger, fork semantics, and the required reason field. The remaining gap is sibling disambiguation from branch_chain, which matters given the crowded sibling set.

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?

Reported schema coverage is 0% for the top-level schema, though the nested $defs carry per-field descriptions. The description adds meaning only for spawn_reason (required, and why), ignoring parent_chain_id, chain_type, title, and completion_vision. Marginal added value keeps this at baseline.

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

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

States a specific verb (fork/spawn) and resource (chain) plus the triggering condition: work needing a different type. The fork-vs-morph semantics are clear. It does not, however, distinguish itself from the sibling branch_chain, leaving the agent to infer the boundary.

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

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

Gives a clear trigger: 'when work needs a different type (Decision 5)'. This tells the agent when the tool is appropriate. It names no alternatives or exclusions, so a reader can't tell how it relates to branch_chain or create_chain from the description alone.

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

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

Annotations already declare readOnlyHint=false, destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety and repeatability profile is fully covered elsewhere. The description adds nothing beyond that — it does not say whether removing a non-existent tag errors, whether add is idempotent, or that removal is the destructive path.

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

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

One short sentence, front-loaded with the two supported operations, with zero filler. Nothing in it is redundant.

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

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

With an output schema present, return values need not be explained, and annotations cover the safety profile. However, for a tool that can destructively strip tags, the description omits any note on tag identity/normalization or whether both add and remove may be supplied at once.

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?

Coverage is reported at 0% at the top level, but the nested schema documents add, remove, and ticket_id, and the description only restates 'add or remove tags on a ticket'. It adds no syntax, duplication, or conflict-handling semantics for the two arrays.

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 pair (add/remove) and resource (tags on a ticket), which is clear and actionable. It does not distinguish itself from the sibling update_ticket, which plausibly touches ticket fields including tags, so an agent gets no help choosing between them.

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

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

No when-to-use guidance, no prerequisites, and no mention of alternatives such as update_ticket for broader edits. The add/remove phrasing implies the operation's shape but leaves selection entirely 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 this as a non-read-only, destructive, idempotent operation. The description adds no further behavioral context—it does not explain what state is overwritten, what permissions are needed, or what side effects occur. It merely restates the operation without contradiction.

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. The stage sequence is compact and readable, and every word earns its place.

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

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

For a destructive capacity mutation with many sibling tools and low top-level schema coverage, the description omits when to use it, what role and trigger mean, and how it relates to other capacity tools. Output schema and annotations help, but core usage and parameter context are 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 0% at the top level, so the description should compensate. It only lists the allowed new_stage values; it says nothing about the 'role' or 'trigger' parameters, leaving key inputs 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?

The description states a specific verb (Record) and resource (stage transition), and it enumerates the exact stage values. It is clear what the tool does, but it does not differentiate itself from sibling tools like record_capacity_event or update_capacity_stage beyond the 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?

There is no guidance about when to use this tool versus alternatives such as record_capacity_event, read_capacity, or check_stagnation. The description simply states the action without context 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?

Annotations already declare destructiveHint=true, idempotentHint=true, and readOnlyHint=false, so the bar is lower, but the description adds nothing beyond the field list. It does not say that updates overwrite existing metadata, whether omitted/null fields are left unchanged or cleared, that 'note' appends rather than replaces, or whether authorization is required for a destructive write.

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, front-loaded fragment with no filler, but it is under-specified rather than genuinely concise. The brevity comes at the cost of the routing and behavior 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?

For a destructive mutation tool with heavy sibling overlap, the description is missing critical context: which sibling to prefer, how null/omitted fields behave, and what the destructive write actually changes. An output schema exists, so return values need not be explained, but the remaining gaps are significant.

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 reported at 0%, so the description carries weight, and its field list (vision, entity, capacity_role, notes) does map onto completion_vision, entity, capacity_role, and note. It omits the required chain_id entirely and says nothing about the null/default semantics of each field, so it only partially compensates for the coverage gap.

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

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

The description names a specific verb-plus-resource ('metadata updates') and enumerates the fields affected (vision, entity, capacity_role, notes), so the basic purpose is clear. However, it does not distinguish this tool from siblings that touch the same fields, notably set_chain_entity and rename_chain, leaving the agent to guess which entry point 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?

There is no guidance on when to use this tool versus set_chain_entity, rename_chain, or set_chain_status, which all mutate overlapping chain attributes. No prerequisites, no indication of what happens if a field is omitted, and no exclusions 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?

Annotations declare destructiveHint=true and idempotentHint=true, but the description never explains what is overwritten (entity, priority, description are replacements) or that omitted fields are left untouched. 'Append a note' even suggests additive behavior that sits awkwardly beside destructiveHint=true, without resolving the difference.

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 efficient sentence that is front-loaded with the verb and resource. It is arguably too terse rather than bloated, but nothing in it is wasted.

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

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

For a destructive mutation touching five parameters, the description omits permissions, partial-update semantics, and the effect of null/default values. An output schema exists so return values are covered, but the mutation contract itself is under-specified.

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 exposes five updatable fields (ticket_id, note, entity, priority, description), yet the description only alludes to 'metadata' and 'note'. With schema description coverage reported at 0%, the description fails to compensate by clarifying which fields are mutable, that priority is an enum, or that all fields except ticket_id are optional.

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 clear verb (update) and resource (ticket), and names the two operation types: metadata changes and appending a note. It does not differentiate from siblings that also mutate tickets, such as tag_ticket, promote_ticket, or link_ticket_chain, so an agent must still infer the boundary from 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?

There is no when-to-use guidance, no exclusions, and no pointer to alternatives like tag_ticket or promote_ticket. The agent is left to guess whether updating a tag or priority belongs here or in a sibling tool.

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