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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the audit is read-only, changes nothing, reports findings via checks, and that zero findings is not proof; however, it leaves the accept/ledger actions and their state implications unclear, which matters for an 11-parameter tool with no annotation safety profile.

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 a single, front-loaded sentence with no wasted text. It efficiently communicates the core operation, immutability, and a key caution.

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

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

For a complex tool with 11 parameters, nested options, and no output schema, the description covers the high-level purpose but does not explain return format, action modes such as accept/ledger, or how findings are surfaced. The rich schema compensates for parameter documentation, but the description alone is only adequate.

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

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

Schema description coverage is 100%, so all 11 parameters already have documented meaning in the schema. The description mentions checks and scoping in passing but adds no parameter semantics beyond what the schema already provides, so the baseline of 3 is appropriate.

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

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

The description states a specific action and resource: a read-only review pass over files that reports findings via checks and changes nothing. It clearly distinguishes audit behavior from mutating siblings by emphasizing read-only operation, but it does not name or contrast against any specific sibling tool.

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

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

It gives implied usage context by saying the pass can run on files you touched or any scope, and warns that zero findings is not proof. However, it does not explicitly state when to use this versus code_check, code_maintain, or other siblings, nor does it describe 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses atomicity, that the default is a preview (dry_run), and the create-file recipe, but says nothing about failure/rollback reporting, validation-gate behavior, or the allow_unsafe_no_base gate — significant gaps for a destructive multi-file writer.

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

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

Front-loads the atomic-write contract and the sibling routing in a single dense sentence; zero filler. The create-mode fragment is telegraphic but still parseable, and nothing is buried.

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

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

For a 10-parameter nested mutation tool with no annotations and no output schema, the description covers atomicity, preview default, and creation, but omits conflict/guard semantics and what a failed batch returns. The rich schema compensates for most parameter gaps, but behavioral completeness for a write tool is only adequate.

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

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

Schema coverage is 100%, so baseline is 3, and the description adds meaning on top: it maps create:true to content + locator.file_path and clarifies dry_run's default to preview. The policy, safety, guard, and idempotency params are left to the schema, which already documents them.

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

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

Specific verb+resource+scale: 'Apply edits to N files in ONE atomic call' with the explicit constraint 'all or nothing'. It also names the sibling that handles single edits (code_patch) and flags the create path, so an agent can distinguish it from code_patch and edit_transaction without opening a schema.

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

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

Gives an explicit routing rule: multi-file atomic edits here, 'single edit → code_patch', and states dry_run defaults to preview. It does not cover when to prefer edit_transaction or invoke_capability, but the primary alternative is clearly named.

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

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

With no annotations, the description carries the full burden and does meaningful work: it discloses the evidence side effect (commands + results recorded against a task), the preview-first safety behavior implying execution requires an explicit opt-in, and that async mode must be polled via code_control. It stops short of failure/exit semantics and any permission or rate considerations.

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 compact clauses pack purpose, evidence recording, the shell alternative, preview behavior, and the async escape hatch with zero filler, and the core action is front-loaded. The telegraphic phrasing ('async:true for long suites') is efficient but slightly at the cost of readability.

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

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

For a 10-parameter execution tool with no annotations and no output schema, the description covers intent, safety preview, and async handling but leaves the response shape, failure semantics, and the verifier modes entirely unexplained. Enough to call it correctly in the common case, not enough to call it confidently in edge cases.

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

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

Schema coverage is 100%, so the schema already documents all ten parameters, making 3 the baseline. The description adds only scattered meaning (async ties to code_control, checks defaulting) and says nothing about verifier, timeout, workdir, or expected_state_revision, all of which are terse one-word schema descriptions.

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

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

States a concrete verb+resource: run test/typecheck/lint, scoped to 'after editing', plus two differentiators (records evidence, precedes execution with a preview). It positions itself against raw shell and points to code_control for background results, but never names the read/audit siblings it might be confused with.

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

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

'Run ... after editing' gives a clear trigger, and 'async:true for long suites' gives an explicit conditional for switching modes. It also advises preferring this over raw shell. Missing is any explicit when-not guidance (e.g., when to use code_audit or code_query instead of re-running checks).

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

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

With no annotations, the description carries the full disclosure burden. It notes that resume 'returns a self-contained brief', which is useful, but says nothing about whether cancel/reopen are destructive, what happens to an interrupted job, permission requirements, or the role of the expected_state_revision guard. For a lifecycle-mutation tool this is a significant 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?

A single front-loaded sentence listing operations with no filler. The one parenthetical adds real value. It is compact, though the enumeration is incomplete relative to the action enum.

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

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

For a 10-parameter, 8-action, unannotated mutation tool with no output schema, the description covers only half the actions and one return value. An agent still lacks enough to select the right action safely or predict effects of cancel/reopen/switch_route.

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

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

Schema description coverage is 100%, so the schema baseline already documents all ten parameters, including the enums. The description only adds meaning for resume's return value; it does not explain ref, goal, route, or how expected_state_revision interacts with the actions, so it stays 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?

Opens with a specific verb+resource phrase ('Manage task lifecycle') and names four concrete operations (cancel, resume, reopen, check job). However, it omits three of the eight enum actions (switch_route, expand, cancel_job) and gives no hint of how it differs from siblings like code_task or code_status.

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 is present, and no alternatives are named. An agent cannot tell from the description why it would call code_control rather than code_task or code_status, nor which of the unlisted actions apply.

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

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

With no annotations at all, the description carries the full burden. It usefully discloses that plan is the default and that dead code is only flagged, never removed — real safety context. However it omits that apply mutates files on disk, says nothing about idempotency (request_id) or the optimistic guard (expected_state_revision), leaving meaningful behavioral gaps for a 10-param write tool.

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

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

Two tight clauses, front-loaded with the action, zero filler. It could be marginally clearer about what happens on apply, but nothing is wasted.

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

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

No output schema and no annotations mean the description must carry safety and return semantics, yet it only covers the preview-flag and dead-code policy. For a 10-parameter mutation tool with fingerprints and revision guards, that is adequate but not 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 100%, so every parameter is already documented and the baseline is 3. The description reinforces the plan/apply duality but adds no syntax beyond the schema (e.g. fingerprint semantics for proposals are left to the schema).

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

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

States a specific verb and resource ('Clean up imports in files you touched') with the scope qualifier 'files you touched', which distinguishes it from a general patcher like code_patch. It stops short of naming a sibling, so 4 rather than 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?

'plan = preview by default' implies the safe-first workflow, and 'dead code is never removed automatically' implies a boundary. But there is no explicit statement of when to choose this over code_patch or edit_transaction, and no prerequisites given.

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

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

With no annotations, the description carries the behavioral burden and usefully discloses reversibility, `dry_run` preview default, and read-before-write via `read_ref`. However, for a 15-parameter mutation tool it omits validation-gate behavior, unsafe-write override, idempotency, and what happens when `dry_run:false` applies changes.

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 dense and front-loaded: purpose, modes, and the important `dry_run` default are all stated without wasted words. 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?

The schema fully covers parameters, and the description gives the core workflow for patch/create and preview/apply. But with no annotations and no output schema, it should say more about validation behavior, idempotency, and return/result semantics for a complex mutation tool.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description adds some context for `read_ref`, `create`, `content`, and `dry_run`, but leaves many parameters such as `safety`, `boundary`, `preserve_decorators`, and `expected_state_revision` to the schema.

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

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

States a specific verb, 'Edit', and a clear resource, 'any text file (code, md, config)', plus two operation modes. It positions itself as a reversible alternative to Edit/Write, but does not explicitly differentiate from sibling `edit_transaction`.

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

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

Explains when to use patch mode with `read_ref` for text already read, and when to use `create:true` with `content` and `locator.file_path`. It also states the `dry_run` default behavior, though it gives no explicit when-not guidance or sibling comparison.

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

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

With no annotations provided, the description carries the full behavioral burden. It discloses 'Read-only' and 'no task needed', which are useful traits, but it does not explain mode-specific effects, output behavior, or the workspace indexing side effect mentioned in the schema.

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

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

The description is compact and front-loads the core purpose before listing modes. The mode list is long but necessary; it omits 'capability' even though the schema enum includes it, which slightly reduces precision.

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?

This is a complex 20-parameter, multi-mode tool with no output schema and no annotations. The description does not explain return values, mode selection, pagination, or the auto-indexing behavior, leaving significant gaps for an agent to infer from the schema alone.

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

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

Schema description coverage is 100%, so the schema already documents all 20 parameters in detail. The description lists the mode names and gives high-level lookup examples but does not add parameter meaning beyond what the schema provides.

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

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

The description states a clear lookup purpose and gives concrete examples: 'where is X, who calls it, what's in this file.' It lists the available modes, making the tool's scope distinguishable from task-oriented siblings. It stops short of naming a sibling, so it is clear but not fully differentiated.

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 'no task needed' implies when to use this instead of task-based tools, and 'Read-only' clarifies the safety posture. However, it does not explicitly compare against siblings like code_read, code_task, or code_search, nor does it explain when each mode should be selected.

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

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

With no annotations, the description carries the full burden. It usefully discloses that the tool returns content plus a read_ref to pass back during editing and that budget_hint=0 returns the full file, but it does not cover permissions, error behavior, or broader read-only guarantees.

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 two compact sentences, front-loads the primary purpose, then adds the return and budget details. Every clause earns its place with no wasted text.

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 tool with seven parameters, a nested locator object, and no output schema, the description is minimal. It covers the core action and return artifact but leaves locator formats, required workspace/task context, and expected_state_revision guard behavior to the schema.

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

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

Schema description coverage is 100%, so the schema already documents all parameters. The description restates budget_hint=0 and the read_ref lifecycle but adds no extra syntax or anchor detail beyond what the schema provides.

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

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

The description states a specific verb and resource: reads a file or one symbol. It also names the timing (before editing) and the return artifact (content plus read_ref). It does not distinguish itself from siblings such as code_query, so it falls short of a 5.

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

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

The phrase 'before editing' gives clear usage context, and the read_ref return value explains the follow-up workflow. It does not name alternatives or when-not-to-use cases, so it is not a 5.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the shape of the returned payload (state, files, evidence) and the listing fallback behavior, which implies a read-only inspection, but it never states that explicitly, nor any permission or scope requirements. Useful but incomplete for a zero-annotation tool.

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

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

Two compact clauses, the primary purpose front-loaded and the mode switch second. Every fragment carries information; nothing is padded.

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

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

For a simple 2-parameter tool with full schema coverage and no output schema, the description says what is reported and how to get a list instead of a single task. The main remaining gap is not saying what 'active' means or what happens when a task_id is unknown.

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

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

Schema description coverage is 100%: task_id already says 'omit = list' and workspace_dir says 'Project root (abs).' The description restates the omit-to-list behavior and adds 'active' as a qualifier on the listing, but adds no real semantics about what a task_id accepts or what workspace_dir scoping means. Baseline 3 is appropriate.

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

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

Specific verb and resource: reports what a task changed so far, naming the returned facets (state, files, evidence). It also covers the dual mode (single task vs. list). It does not distinguish itself from siblings like code_audit, code_query, or code_check, 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?

'Omit task_id → list active tasks' gives explicit mode-selection guidance, which is genuinely useful. However there is no guidance on when to prefer this over sibling status/audit tools (code_audit, code_query, code_check) and no stated exclusions, leaving usage implied rather than specified.

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

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

With no annotations, the description carries the full burden, and it does disclose the critical trait: this tool does not mutate or verify anything. It also names the three payload kinds (candidates, structure, impact). It says nothing about cost, whether prior indexing/workspace state is required, or determinism of the returned candidates, which matters for a planning call intended as the first step.

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 call-to-action and closed with the follow-on chain; nothing is padded. The arrow-chain notation is dense to the point of being telegraphic, which costs a little readability against the otherwise tight structure.

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

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

For a 6-parameter, nested-object, no-output-schema tool, the description covers the two things an agent most needs: when to call it and what happens next. Parameter-level detail is delegated entirely to a fully-covered schema, and return shape is only named, not characterized — acceptable given no output schema exists but not exhaustive.

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

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

Schema description coverage is 100%, so goal, route, target, request_id, search_terms, and workspace_dir are already documented in the schema, making 3 the baseline. The description mentions only 'describe the goal' and adds no guidance beyond the schema — notably it never explains when to override route or how target anchors steering, even though route inference ('Inferred when omitted') is a meaningful behavioral lever.

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 concrete purpose: a planning call that takes a goal and returns candidates, structure, and impact in one shot. It differentiates from siblings by naming the read/patch/check sequence that follows. What it lacks is a crisp verb+resource label (e.g. 'plan a code change'), leaving 'start here for any change' slightly open-ended about the artifact produced.

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 trigger ('Start here for any change'), an explicit exclusion ('Planning only — does not itself edit or check'), and names the alternatives plus their order (code_read → code_patch / code_batch → code_check). An agent can route correctly without inspecting any other 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?

With no annotations, the description carries the full burden and does disclose meaningful behavior: edits happen in an isolated temp worktree, the verify command gates the outcome, and the commit only fast-forwards to the current branch on pass. It omits auth/permission requirements, idempotency semantics (despite a request_id param), and the rollback-on-preview distinction, keeping it short of a 5.

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

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

A single well-formed sentence that front-loads the value proposition and uses a colon to unpack the mechanism. Dense but zero filler; it does not waste space on restating the name.

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

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

For a 10-parameter tool with three actions (preview/apply/status) and no output schema, the description addresses only the apply path. Preview and status modes — and what a caller should expect from them — are left entirely to the schema, leaving the multi-mode behavior under-explained.

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

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

Schema description coverage is 100%, so every parameter is already documented, establishing a baseline of 3. The description reinforces the gating role of the verify command but adds no format or usage detail beyond what the schema states.

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

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

The description names a concrete mechanism (temp git worktree + verify gate + fast-forward commit into the CURRENT branch), which tells an agent exactly what the tool accomplishes. The verb is somewhat implicit ('apply runs edits') and it never names or contrasts with siblings like edit_transaction or code_patch, so differentiation falls short of a 5.

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

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

The phrase 'Land a risky change safely' implies the intended scenario (high-risk edits needing verification), which is useful implied guidance. However, there is no explicit when/when-not, and no routing to the alternative transaction/edit tools that occupy the same space.

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

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

No annotations are provided, so the description carries the full behavioral burden. It discloses the transactional rollback/undo model and workflow, but omits mutation risks, atomicity semantics, action-specific side effects, and error/concurrency behavior.

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

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

A single sentence, front-loaded with the core capability and workflow. Every clause earns its place and there is no redundant text.

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?

This is a 16-parameter, 9-action mutation tool with no annotations and no output schema. One sentence does not adequately explain actions like edit_chunk, assemble, undo_commit, info, or the roles of atomic, dry_run, create, and txn_id; the schema descriptions are too terse to fill those 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 100%, so the schema already documents all 16 parameters, establishing a baseline of 3. The description adds little parameter-level meaning beyond the begin->edit->commit sequence and relies on the schema's terse field descriptions.

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

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

States a specific capability: multi-file edit with rollback/undo via begin->edit->commit. It also distinguishes itself from single-file edits, though it does not name a specific sibling alternative.

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

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

Gives explicit when-to-use guidance (multi-file edits needing rollback/undo) and when-not-to-use guidance (single-file edits don't need one). It does not name the preferred tool for single-file edits.

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

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

With no annotations, the description carries the full burden and does well: it discloses the single-shot delegation model ('once per call — no retries') and the mutation risk ('read-only unless the target itself writes'). It leaves failure handling and auth prerequisites unstated, but the key behavioral traits an agent needs are present.

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

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

A single dense line that front-loads the purpose, then the delegation semantics, then the selection guidance. Every clause earns its place with zero 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?

Given a nested-args escape hatch with a fully-described schema and no output schema, the description covers purpose, delegation model, retry behavior, and write risk adequately. Only error/response handling is left implicit, a minor gap against the rich schema.

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

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

Schema description coverage is 100%, so the schema already documents name, args, workspace_dir, task_id, and request_id thoroughly. The description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description opens with 'Escape hatch: call a tool not listed above, by exact name' — a specific verb, resource, and mechanism. It distinguishes itself from the listing-focused siblings by making clear it is the fallback for tools not surfaced elsewhere.

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

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

Explicitly states when to reach for it ('call a tool not listed above') and when not to ('Prefer listed tools'), which routes the agent away from it by default. It stops short of naming a concrete sibling alternative, but the guidance is clear and actionable.

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