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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is established. The description usefully adds scope details beyond that (relative to HEAD, includes non-ignored untracked files, snapshot identity, no graph build, no tests), but says nothing about the shape of the returned data or how snapshot identity is used.

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

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

Two sentences, zero filler. The scope statement is front-loaded and the exclusion clause follows immediately as supporting contrast.

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-optional-parameter read tool with no output schema, the definition covers what is enumerated and confirms the absence of side effects. It stops short of telling the agent what the return value looks like (path list format, snapshot identity field), which would be the remaining useful detail.

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 with 100% schema description coverage, including precise guidance about passing the edited repository when using a plugin. The prose adds nothing about the repo argument, so the schema carries the full burden and 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 pairs a specific verb ('List') with a precisely scoped resource ('staged, unstaged and non-ignored untracked changed paths relative to HEAD') and adds a snapshot identity. The closing clause ('Builds no dependency graph and runs no tests') implicitly separates it from siblings like diffci_check and diffci_select_tests, so an agent can pick it without opening another schema.

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

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

It gives clear context for when this is the right tool: the agent needs changed paths only, not a graph or a test run. The explicit exclusions act as when-not guidance, but no sibling is named as the alternative for those other needs, so routing between diffci_check and diffci_select_tests is still left to inference.

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

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

With no annotations supplied, the description carries the full burden, and it does disclose meaningful behavior: no report is uploaded, telemetry is aggregate and consent-gated, and DIFFCI_NO_SEND=1 overrides it. It is silent on the operational side effects of executing test commands (working-tree writes, runtime cost, failure handling), which matters for a tool that runs commands.

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 that front-load the action and follow with privacy constraints; nothing is padded. The privacy sentences are dense but each carries distinct information (no upload, consent-gated telemetry, env override).

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 six-parameter tool with no annotations and no output schema, the description covers purpose and privacy but omits what the 'paired runtime' report contains and how command execution failures surface. The agent has enough to call it, but not enough to predict its output or side effects confidently.

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

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

Schema description coverage is 100%, so all six parameters (base, head, json, quiet, redactPaths, repo) are already documented in the schema. The description adds no additional meaning about defaults or interactions between them, 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 concrete verb chain (analyze repo, run inferred full and selected test commands, report paired runtime), which is specific enough for an agent to know what it produces. It does not, however, distinguish itself from siblings like diffci_run_affected_tests or diffci_verify, which plausibly also run tests.

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

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

There is no explicit when-to-use or when-not-to-use guidance, and no mention of the sibling tools it competes with. 'When available' hints at a fallback behavior for test command inference, but nothing tells the agent why to pick this over diffci_run_affected_tests or diffci_verify.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds useful behavioral context beyond that: it inspects staged, unstaged, and non-ignored untracked changes, returns a snapshot-bound plan and fallback reasons, runs no tests, and clarifies that a plan is not a passing receipt. It does not describe how the plan is computed or how fallback reasons are generated, so it stops short of a full behavioral account.

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 tight sentences with no wasted wording. The core scope is front-loaded, and the second sentence adds an important boundary condition without repetition.

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 low-complexity, single-optional-parameter, read-only tool with no output schema, the description covers what is inspected, what is returned, and the key limitation that no tests are run. It is nearly complete, though the exact shape of the affected-test plan and fallback reasons remains somewhat open.

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 sole optional repo parameter is fully documented in the schema. The description adds no additional meaning about the repo parameter, so the schema does the heavy lifting and the baseline score applies.

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

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

The description states a specific action and resource: inspect staged, unstaged, and non-ignored untracked changes and return an affected-test plan with fallback reasons. It distinguishes itself from test-running siblings by saying it runs no tests, though it does not explicitly name nearby tools like diffci_select_tests or diffci_changed_files.

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: use this to obtain an affected-test plan and fallback reasons without executing tests. However, the description does not explicitly say when to choose it over diffci_select_tests, diffci_changed_files, or diffci_check, nor does it state exclusions beyond 'runs no tests'.

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 concrete artifacts written, which signals a mutating scaffolding operation. However, it says nothing about idempotency, what happens to pre-existing files on re-run (that semantics lives only in the 'force' schema field), whether it touches Git state, or what it returns on success/partial 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 sentence, front-loaded with the action verb, enumerating only the artifacts created. No filler, no restatement of the tool name, nothing that could be cut without losing information.

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

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

For a seven-parameter mutating tool with zero annotation coverage and no output schema, the description covers only what is produced, not prerequisites, re-run safety, or observable results. It is adequate to understand the tool's intent but leaves enough behavioral gaps that an agent could misuse it in an already-initialized repo.

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 seven flags are already documented with defaults and target paths in the schema. The description adds no mapping between its enumerated artifacts and the corresponding switches (mcp, hook, skill, workflow, verificationWorkflow), so the baseline 3 applies.

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

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

The description opens with a specific verb ('Seed') and an enumerated resource set: agent instruction files, MCP server configs, the diffci-verify skill, and the pre-push hook. This clearly separates it from all siblings, which are verify/check/select/run tools. It falls short of a 5 only because it never states the scope framing ('first-time setup of a repo') that would make the distinction explicit rather than inferred.

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?

'Seed a repository' hints at initialization, but there is no explicit when-to-use statement, no prerequisite (e.g. must be a Git repo), no guidance on re-running in an already-seeded repo, and no reference to the diffci_verify/diffci_check siblings it presumably precedes. An agent must infer the entire usage context from the verb.

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 openWorldHint=false, so the agent already knows this is a non-read-only, closed-world operation, and the description is consistent with that. Beyond the annotations, the description usefully discloses the result-authority caveat versus CI and the possibility of an expensive conservative full-suite fallback. It does not say what state is written, how long a full run may take, or how the timeout interacts with that fallback.

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 action and the fallback behavior, with no filler. The main clause is slightly dense and could be split, 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?

There is no output schema, so the description must explain what a run produces, yet it never says whether the result is a pass/fail, a selected-test list, or a report path. For a tool that may execute a full test suite, the omission of return shape and cost/blocking characteristics leaves an agent unable to predict the outcome of 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?

Two parameters with only 50% schema description coverage: repo is documented in the schema, but timeoutMs has no description anywhere. The tool description adds nothing about either parameter, not even that timeoutMs bounds the potentially long fallback run, 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?

The description names a specific action and target: reanalyze and verify the current working-tree snapshot using affected tests, with a full-suite fallback. That is concrete enough for an agent to know what the tool does, but it draws no line between itself and near-identical siblings such as diffci_verify_changed, diffci_verify, or diffci_check.

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 signal is the trailing clause that required CI remains authoritative, which hints this is a local pre-flight rather than a replacement for CI. There is no explicit when-to-use, no when-not-to-use, and no mention of any of the nine sibling tools despite obvious overlap with the other diffci_verify_* tools.

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

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

Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds genuinely new behavioral context: the plan is snapshot-bound, it includes fallback reasons, and crucially the output is advisory rather than a passing result. It does not describe failure modes or what triggers fallback reasons.

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

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

Two tightly packed sentences with zero filler; the positive capability is front-loaded and the critical caveat follows immediately. Every clause carries information an agent needs.

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

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

With only one optional parameter, no output schema, and read-only annotations, the description covers the essentials and explicitly characterizes the return value. Minor gaps remain around how the plan is scoped (affected tests relative to what baseline) and behavior on a clean working tree.

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 parameter is already documented in the schema, including its default. The description adds no additional meaning about how repo affects the diff scope, so the schema is doing the heavy lifting and 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 ("Inspect") against a specific resource (staged, unstaged, and non-ignored untracked changes) and names the concrete return artifact: a snapshot-bound affected-test plan plus fallback reasons. It is clearly differentiable from the sibling diffci_run_affected_tests via "Runs no tests," though it never names that sibling 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?

"Runs no tests; a plan is not a passing receipt" gives a clear when-not boundary, steering the agent toward a run/verify tool when actual test execution is required. It stops short of explicitly naming the alternative tool or stating preconditions (e.g., behavior when there are no changes), so it is not a full 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 supplied, so the description carries the full burden. It discloses two real behaviors: the result is a receipt tied to the checked-out HEAD, and the range is auto-derived from CI context when base/head are absent. It omits whether verification commands are executed (implied only by timeoutMs), what a failed verification means, and whether any state is written, which matters for a tool with a timeout and command-runtime implication.

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, no filler, with the outcome and the default-range behavior front-loaded. Nothing could be removed without losing information.

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

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

Placeholder.

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 five parameters are already documented, including the base/head pairing constraint. The description adds only the omitted-parameter behavior (automatic CI range resolution); it says nothing extra about timeoutMs semantics or redactPaths effects 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 ('Verify') and resource ('a clean commit range') plus the artifact returned ('a receipt bound to the checked-out head commit'). It does not differentiate itself from near-name siblings like diffci_verify_changed or diffci_verify_workflow, so an agent cannot tell from the description alone which verify variant 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 second sentence gives one useful usage rule: omit base and head to auto-resolve the CI event range. There is no guidance on when to pick this over diffci_verify_changed, diffci_check, or diffci_verify_workflow, which is the main ambiguity an agent faces given the sibling set.

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 behavioral burden. It does disclose a fail-closed policy and that the snapshot must match exactly, which is genuinely useful. However, it never says that this executes verification commands, what those commands are derived from, what permissions or repo state are required, or how failure is surfaced — all critical for a tool whose timeoutMs parameter reveals it runs arbitrary-length processes.

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

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

Two tight sentences with the scope stated first and the fail-closed guarantee second; nothing is redundant. Some phrasing ('exact working-tree snapshot', 'selected or full fallback verification') is dense jargon that would benefit from one clarifying clause, but the size is appropriate.

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

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

There is no output schema and no annotations, so the description is the only source of behavior. It omits what a verification result looks like (pass/fail, per-test detail, diagnostics), what 'selected vs fallback' means operationally, and whether it mutates the working tree. For a fail-closed verification gate, these omissions leave 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 100%, so repo, timeoutMs, and redactPaths are already documented in the schema. The description adds no parameter-level meaning beyond implying working-tree scoping. Baseline 3 applies since the schema does the heavy lifting.

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

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

States a specific verb ('Verify') and a precise resource scope: staged, unstaged, and non-ignored untracked changes. That scope implicitly separates it from siblings like diffci_changed_files or diffci_verify, but the description never names an alternative, so an agent must infer the distinction from sibling names alone.

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 'working-tree snapshot' framing implies this is the tool for pre-commit / uncommitted-change verification rather than committed-diff verification, but there is no explicit when-to-use or when-not-to-use guidance relative to diffci_verify, diffci_check, or diffci_verify_workflow. The mention of 'selected or full fallback verification' hints at selection behavior without telling the agent how to control it.

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

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

No annotations are provided, so the description carries the full disclosure burden. It implies a read-only check but never says whether it mutates state, what a failing verification means, whether it exits with an error or returns a result, or what the agent should do with a negative outcome.

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. It is efficient, though its brevity is part of why coverage is thin elsewhere.

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 verification tool with no output schema and no annotations, the description should at minimum explain what a pass/fail looks like and what is examined. As written, an agent cannot tell what the tool returns or what 'cannot affect the rest of CI' concretely checks.

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

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

The single 'repo' parameter has a full schema description including its default, so the schema does the work here. The description adds no meaning beyond it (e.g., whether the repo must contain DiffCI config or a workflow file).

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 ('Check') and a resource ('a DiffCI GitHub Actions job'), plus a goal ('cannot affect the rest of CI'), so the general intent is inferable. However, 'cannot affect the rest of CI' is ambiguous — it never states what is actually being validated (workflow isolation, path filtering, permissions) and gives no clue how it differs from the closely named siblings diffci_verify and diffci_verify_changed.

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 call this versus diffci_verify, diffci_verify_changed, or diffci_check, and no stated preconditions. The agent must guess based on name alone.

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