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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, but the description goes further: it says the report is overwritten with a fresh UTC timestamp so repeated calls are not idempotent, that it errors when the Markdown file cannot be written, and that it only reads health_history, fix_log and pending_fixes without inferring fixes from Git. That is exactly the kind of context annotations cannot convey.

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

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

Front-loaded with the artifact name, then organized into explicit 'Use when' / 'Don't use when' blocks and a short behavior paragraph. Every sentence adds a fact an agent needs (side effects, data sources, error condition); nothing is filler.

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

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

For a one-parameter write tool with an output schema already declaring {success, path}, the description covers the remaining gaps: which state files are read, what is not inferred, overwrite/non-idempotency, and the failure mode. Nothing an agent needs to call this correctly is missing.

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

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

Schema description coverage is 100% and the single repo_path parameter already documents the required state file, the overwrite behavior and the timestamp. The description adds no path-format or validation detail beyond that, so the baseline 3 is appropriate when the schema carries the parameter semantics.

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

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

States a concrete verb (write) and named artifact (REFORGE_CHANGES.md) plus the exact data sources: saved health history, fixes and pending work. An agent can distinguish it immediately from read_memory and from the scanning siblings because the description explicitly says it does not rescan.

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?

Provides both a positive trigger ('Use when: you need a human-readable report of state recorded during cleanup') and a negative one with a named alternative ('Don't use when: you only need one raw saved state value (use read_memory instead)'). The routing decision between this tool and a sibling is fully 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?

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds value beyond that: binary/lock/minified guards still apply, large files can be sliced, and failure returns {error}. It does not reintroduce the safety hints redundantly.

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

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

Front-loaded with purpose, then when/when-not, then return shape and guards — every block is scannable and largely earns its place. The explicit return-object breakdown is slightly redundant given an output schema exists, keeping it short of 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 read tool with full annotation and schema coverage plus an output schema, the description supplies the remaining behavior an agent needs: guards, slicing for large files, and the error case. The redundant return-shape sentence is the only mild over-explanation.

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 clamping and defaults are already documented per-parameter, and the description largely restates the clamping rule ('start_line/end_line report the clamped inclusive range'). The one genuinely additive note is that source joins lines with newlines, but overall it adds little beyond the schema.

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

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

States a specific verb and resource with scope: 'Read an inclusive line range from a UTF-8 file without modifying it.' The read-only, single-file, line-range framing immediately separates it from scan_repo, which is named directly.

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?

Uses explicit 'Use when' (inspect a finding, get context for a patch) and 'Don't use when' (repository-wide findings → scan_repo) clauses, naming the alternative sibling and the condition that selects it. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false and destructiveHint=false, yet the description still adds real value: it states that a UTC-timestamped history entry is appended on every call, that repeated calls are therefore not idempotent, and that caveats appear for limited coverage or parse failures. It stops short of saying where state lives or how backups rotate, which only the parameter schema hints at.

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, when-to-use and when-not-to-use are front-loaded and tightly written. The trailing 'Returns {...}' block is informative but partly redundant with the existing output schema, making the definition longer than strictly necessary.

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

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

For a single-parameter tool with full annotation coverage and an output schema, the description covers the write side effect, side-effect caveats and scoring semantics well. The detailed return-value enumeration duplicates the output schema, so it is complete but not optimally scoped.

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

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

Schema coverage is 100% for the single parameter, and the schema description already covers path expectations, persistence to reforge-state.json and backup rotation. The description adds no parameter-level detail beyond what the schema supplies, 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 opening sentence names a specific verb and resource — computing repository health from scan metrics — and adds the persistence side effect. It explicitly differentiates from the sibling scan_repo, so an agent can pick between them without opening either schema.

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

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

Provides an explicit 'Use when' condition (need before/after metric plus persisted history) and an explicit 'Don't use when' that names the alternative (scan_repo for findings without writing state). Both directions of the routing decision are covered.

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

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

Annotations only declare the mutation/open-world profile; the description goes well beyond them by disclosing the checkpoint confirmation flow (needs_confirmation plus retry with confirmed=true), that refusals do not consume the session budget, that empty commits are refused, that initial commits are allowed, that Git hooks may run, and that nothing is pushed. The one omitted behavior is what 'destructive' concretely means here (e.g. whether rewriting history is possible), which keeps it from 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?

Strong structure: purpose first, then labeled use/don't-use, then return shape, then caveats. Every sentence carries information, but the return-value enumeration is partly redundant given an output schema exists, and the tail-end caveats are packed densely into long sentences.

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, open-world mutation with six parameters and an approval gate, the description covers the confirmation retry loop, budget interaction, index semantics, branch switching and hook invocation. Combined with the output schema, an agent has everything needed to call it correctly and to handle the refusal and checkpoint paths.

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

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

Schema description coverage is 100%, so the schema already explains files, branch, message, confirmed, repo_path and create_branch in detail. The description mostly restates those semantics, with the only genuinely additive note being that files_committed echoes the requested list rather than being an inventory of the commit. Baseline 3 is appropriate when the schema carries the parameter burden.

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-plus-resource pair ('Stage the named files and create a Git commit') and adds a scoping constraint ('within the session budget'). It also explicitly names the sibling it is not for ('use write_fix instead'), so an agent can distinguish it from the patch-application tool without opening either schema.

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

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

Gives a labeled 'Use when' condition (edits reviewed and should be recorded in local history) and a labeled 'Don't use when' condition that names the alternative tool write_fix. This is the explicit when/when-not/alternative structure an agent needs for 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 declare readOnlyHint=false and destructiveHint=false but say nothing about what actually gets written. The description fills that gap: it writes architecture_hypothesis into reforge-state.json, rotates existing state backups, and scans without an external model using imported modules plus filename-based heuristics. It also discloses the heuristic nature of confidence, which sets correct expectations about the output.

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

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

Front-loaded with purpose, then use/don't-use, then behavior and return shape — a clean progression with no filler. The return-value enumeration is slightly redundant since an output schema exists, which keeps it from a 5.

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

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

For a single-parameter, non-open-world scan-and-write tool, the description covers the trigger condition, the alternative, the mutation of state with backup rotation, the classification method, and confidence semantics. Nothing an agent needs in order to call it correctly or interpret results is missing.

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

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

Schema coverage is 100% and the single repo_path parameter is fully documented in the schema, including the absolute-path preference and backup rotation note. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

States a specific verb and resource ("Infer a repository's architectural pattern") plus the persistence side effect, and explicitly distinguishes itself from read_memory as the read-only alternative for the saved hypothesis. An agent can separate this from scan_repo or read_memory without opening any schema.

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

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

Provides an explicit "Use when" (need an initial map of likely shape and entry points) and "Don't use when" (only need the previously saved hypothesis → use read_memory instead), naming the sibling to route to. No inference required from the agent.

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

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

Annotations already declare readOnly, idempotent, non-destructive, closed-world, so the safety profile is covered. The description still adds genuine behavioral nuance beyond them: unknown keys return value=null with found=false, and built-in default keys report found=true even when no state file exists — a non-obvious quirk an agent would otherwise misread as real persisted data. It loses a point because the {key, value, found} return summary is largely duplicated by the existing output 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?

Four short sentences, front-loaded with the core action, then the when/when-not routing, then return and edge-case semantics. No filler, and each sentence carries distinct 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 two-parameter read tool with an output schema, full annotations and 100% schema coverage, the description covers action, alternatives, return shape, and the missing-state and default-key edge cases. Nothing material is left for the agent to guess before calling it.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema, including the top-level key examples and the repo_path defaults behavior. The description adds only the 'one top-level value' framing, which the schema's key description already conveys, so the baseline of 3 applies.

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

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

States a specific verb and resource — 'read one top-level value from persisted repository state' — plus a scoping qualifier ('without writing files') that pins down what it does not do. The contrast with write_memory makes it immediately separable from the nearest sibling, and 'one top-level value' rules out nested-path reads.

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?

Uses explicit 'Use when' / "Don't use when" framing, and the exclusion names the alternative tool (write_memory) together with the condition that selects it (replacing a stored value). It also enumerates the concrete key categories (hypothesis, fix queue, fix log, health history) that motivate a call, so no inference is required.

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

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

Annotations already cover safety (readOnly, idempotent, non-destructive, closed-world), and the description goes well beyond them: it discloses the truncation caps (200 items, 50 duplicate groups, 10 locations), the <key>_total companion fields, the guarantee that summary counts stay complete, the Git-index-only-tracked-files rule, and the degraded error response for a bad root. These are non-obvious behaviors an agent could not infer from annotations.

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

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

Front-loaded with purpose, then a when/when-not pair, then return shape, then edge cases and caps — a logical order with no filler sentences. It loses a point for density: the truncation sentence ('shortened lists gain <key>_total, with truncated listing shortened top-level/graph lists') is syntactically tangled and would benefit from restructuring.

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

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

For a three-parameter, read-only analysis tool this covers purpose, alternatives, failure modes, and truncation, leaving little an agent needs missing. Since an output schema exists, the detailed return-field enumeration and summary-contents description are partly redundant, which keeps it just short of a 5.

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 root_path, languages, and include_tests are already fully documented in the schema, including the include_tests no-op caveat. The description adds indirect meaning by explaining that Git index state changes which files under root_path are analysed, but it adds no new detail about the parameter values themselves. Baseline 3 applies.

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

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

States a specific verb+resource ('Scan source files') and enumerates exactly what is detected: dead code, duplicates, oversized modules, dependencies. It also explicitly positions itself against the sibling get_chunk, so an agent can distinguish the two 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?

Provides an explicit 'Use when' (repository-wide findings before planning changes) and an explicit 'Don't use when' that names the alternative tool (get_chunk) and the condition selecting it. This is the strongest form of routing guidance available.

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

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

Beyond the readOnly/idempotent annotations, the description discloses the scoring internals (inbound_refs 0-30, has_tests 0/20, lines_changed 5/10/17/25 based on file length not patch size, is_circular 0/25), the caps (at most 10 referenced paths), the basis fallback (symbol or file when references unavailable), and an explicit caveat that the score is not a guarantee. This is the kind of context annotations cannot carry.

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

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

Usage guidance is front-loaded before the return explanation, and every clause carries real information. The returns block is long and partly duplicates what the output schema may already convey, which keeps it from a 5.

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

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

For a three-parameter, read-only heuristic scorer, the definition covers triggering conditions, internal weighting, output shape, interpretation thresholds, and explicit limitations. Nothing an agent needs to call it correctly or interpret the result is missing.

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

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

Schema description coverage is 100%, so the schema already explains file, symbol, and repo_path semantics including the case-sensitivity and no-validation caveats. The description adds only the framing that exactly one symbol is assessed, so the baseline 3 applies.

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

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

States a specific verb and resource ('Estimate the risk of changing one symbol') plus the output scale (0-to-100 heuristic), which immediately separates it from the aggregate-health sibling get_health_score. An agent can distinguish it from every sibling without opening a schema.

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

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

Explicit 'Use when' gives the triggering condition (prioritizing a specific proposed change before patching) and 'Don't use when' names the alternative tool (get_health_score) with the condition that selects it. Both directions of routing are covered.

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

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

Beyond annotations (destructive, non-idempotent, open-world), the description discloses that no commit is created, that rollback is attempted on failure, that a .reforge-bak file may be retained, and that a diff is not safe to reapply. The caveat 'success without test_command does not mean tests ran' is a non-obvious behavioral trap that annotations cannot express.

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

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

It is front-loaded (purpose, then when/when-not, then returns) and every sentence carries signal. The enumerated return-value list partially duplicates the output schema, which is the only slack in an otherwise tight definition.

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 five-parameter destructive patch tool with an output schema, the description covers purpose, gating conditions, rollback behavior, backup artifacts, and result interpretation. Nothing an agent needs in order to invoke it safely is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds meaning on top by clarifying that test_command is optional and that omitting it yields success without test execution, which changes how an agent should interpret results. It does not add nuance about allowed_test_commands beyond the schema, keeping it below 5.

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

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

The opening sentence names a specific verb and resource ('Apply a unified diff to one file') and immediately adds the two bundled behaviors (optional test run, rollback on failure). It also explicitly distinguishes itself from the closest sibling, git_commit, so an agent can route without opening schemas.

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

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

It provides an explicit 'Use when' condition (you have reviewed the source and prepared a specific patch) and an explicit 'Don't use when' with the named alternative (git_commit for recording existing edits). This is the full when/when-not/alternative triad.

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=false and idempotentHint=false; the description adds the reason behind the idempotency flag (backups rotate, previous_value changes on repeated calls) plus the OSError failure mode, which is genuinely useful context. It also clarifies that other top-level keys are preserved, easing the destructiveHint=false concern. Minor gap: the return-shape sentence partly duplicates the existing output schema.

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

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

Front-loaded with the core action, then structured 'Use when' / 'Don't use when' blocks, then return and idempotency notes. Every sentence carries information; nothing is padding.

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

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

For a three-parameter write tool with full schema coverage and an output schema, the description covers the remaining gaps an agent needs: side effects (backups, replacement semantics), failure mode, and non-idempotency. Nothing material is missing.

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

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

Schema description coverage is 100% and the schema already documents key as a literal (not dotted) key, value as a full JSON replacement, and repo_path's temp-file/backup behavior. The description adds no parameter-level detail beyond what the schema states, so the baseline 3 applies.

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

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

States a specific verb and resource ('Create or replace one top-level value in reforge-state.json via a staged write') and scopes it to a single top-level key, which distinguishes it from read_memory and from other writers in the sibling list. An agent can tell what this does without opening the schema.

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

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

Gives an explicit 'Use when' condition (persisting hypothesis, fix log or pending work across sessions) and an explicit 'Don't use when' with the named alternative (read_memory for inspection). Both the positive and negative routing conditions are stated.

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