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

Annotations only declare it is a non-read-only, non-destructive, closed-world tool; the description adds real behavioral context: it writes files (skeleton, render, README refresh), can fail with a named blocking feature, and records the owner's reason in the new feature's lifecycle. It stops short of describing the success payload, which the output schema already covers.

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. The primary action and its side effects come first, and the gating rule follows immediately after; every clause carries decision-relevant information.

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

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

With 5 parameters at full schema coverage, an output schema for return values, and annotations covering the safety profile, the description supplies exactly the missing layer: side effects and the refusal/override rule. Nothing needed to call it correctly is absent.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema by tying by=owner and reason together and stating that the reason is persisted in the new feature's lifecycle. The name/root/title parameters get no additional treatment, which keeps it from a 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?

States a specific verb and resource ('Write the skeleton of a new spec-loop feature') and enumerates the concrete side effects: next FEAT number, first phase, render, refresh spec/README.md. This is clearly distinguishable from siblings like features (listing), phase (advancing), and render (regenerating output).

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 the precondition and the refusal behavior ('refuses while another feature is not done, naming it') plus the override path via by=owner with a reason. It lacks explicit routing to siblings such as features/status for checking whether an in-progress feature blocks creation, but the when/when-not guidance is clear.

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

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

The annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the description is not responsible for covering the safety profile. It adds genuinely new behavior: the comparison is three-way (regenerated projection, disk files, manifest), and every alteration comes classified with a block id and JSON pointer, which tells the agent what kind of answer to expect.

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

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

It is a single front-loaded sentence that establishes the comparison target first and the result shape second, with no filler or restatement of 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?

With an output schema present and rich annotations, the description covers the comparison semantics and the meaning of the returned hunks, which is what an agent needs in order to call it. The only gap is routing guidance against reconcile and validate, which is a usage-guidelines concern.

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 spells out the fallback chain for root (SPEC_LOOP_ROOT, CLAUDE_PROJECT_DIR, working directory) and the three accepted feature forms. The description adds nothing parameter-level 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?

The description gives a specific verb and resource: it compares a regenerated projection against both the on-disk files and the manifest, and it names what the result contains (hunks with block ids and JSON pointers). It does not, however, distinguish this from adjacent siblings like reconcile or validate, which an agent could easily confuse with it.

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

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

The word 'Compare' plus the mention of the regenerated projection implies the situation where this is useful (checking drift after regeneration), but there is no explicit when-to-use or when-not-to-use statement, and no sibling is named as the alternative. Guidance is inferable but not stated.

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

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

Annotations already declare readOnlyHint, idempotentHint and openWorldHint=false, so the safety profile is fully covered without the description's help. What the description does add beyond that is the side effect of echoing the resolved root and spec path, which tells the agent it can verify which project was actually read. It does not mention ordering, whether the scan recurses, or behavior on an empty spec/ directory.

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

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

One densely packed sentence with the actor and output shape front-loaded and no filler. The field enumeration is long but each item is informative; only slight trimming (e.g. 'pending edits/alterations') would tighten it further.

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

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

An output schema exists, so the description is not obliged to explain return values, and root resolution is fully covered by the parameter schema. For a single-optional-param, read-only listing tool the description plus structured fields give the agent everything needed to call it correctly.

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

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

Schema description coverage is 100% and the root parameter already spells out the full resolution chain (arg, SPEC_LOOP_ROOT, CLAUDE_PROJECT_DIR, cwd). The description's 'echoes the resolved root and spec path' adds a small but real point the schema does not make: the agent can confirm which root won. That is marginal value on top of a self-sufficient schema, so baseline 3 is right.

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 ('One summary line per spec-loop feature'), and enumerates exactly what each line contains (id, name, phase, completeness, pending owner edits, last modification). An agent can immediately tell this is a read-only inventory of features, distinct from action-oriented siblings like create, patch or reconcile. It only misses explicit naming of the closest rival (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?

The description never says when to reach for this instead of the sibling 'status' or 'diff' tools, nor any prerequisite. The only usage-adjacent information (pass root on every call, with a fallback chain) lives entirely in the schema, not the description.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds that topics are generated from the schema, but it does not add much behavioral context beyond what annotations and the output schema provide.

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

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

The description is short and front-loaded, stating the core behavior before listing topics. The topic list is somewhat redundant with the enum, but it remains useful and does not bloat the 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 one-parameter read-only tool with an output schema and rich annotations, the description is mostly complete. It explains what is returned and lists valid topics; the output schema handles return structure, so no major gaps remain.

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 topic parameter is fully enumerated with a default documented in the schema. The description repeats the topic list but does not add meaning beyond the schema, 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 verb and resource: it returns one topic of the spec-loop method, and it enumerates the available topics. The purpose is clear, but it does not differentiate itself from siblings such as phase, features, or 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?

The description implies usage as a documentation/topic lookup by saying it returns one topic and listing valid topics. However, it does not state when to choose this tool over siblings like phase or features, nor does it provide any exclusions or prerequisites.

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

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

Adds real behavior beyond the annotations: validation gating before any write, a re-render side effect, and an explicit list of non-patchable fields (id, name, phase, lifecycle) that would otherwise be discovered only by failure. It does not say whether ops are applied atomically or what state remains if a mid-sequence op fails, which is the notable gap for a mutation tool.

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

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

Two sentences, both load-bearing: the first packs the operation, format, safety gate and side effect; the second carries the only field-level constraint. Front-loaded with the action and zero 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?

With annotations declaring a non-readonly, non-open-world operation and an output schema present, the definition covers what an agent needs to invoke it: target identity, format, gating, side effects, and forbidden fields. Failure semantics (atomicity, partial-application state) are the only meaningful omission.

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 67% and both root and feature carry schema descriptions, so the baseline is 3. The description earns an extra point by constraining what paths the `ops` array may legally target ('id, name, phase and lifecycle are not patchable'), a path-level rule the schema cannot express.

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 standard (Apply an RFC 6902 JSON Patch) against a specific resource (spec-loop feature.json), then describes the full pipeline: validate, conditional write, re-render. This distinguishes it from the validate and render siblings, which it internally subsumes, and from create.

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 conditional write ('write only when no invalid error remains') implies the validation gate and hints that a separate validate call is not needed first. However, it never explicitly says when to reach for patch versus create, validate, or render — the routing 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?

Goes well beyond the annotations by disclosing the gating logic (hook exit codes, pending owner edits), the side effects (runs onEnter hooks of the entered phase, records a history entry plus every hook run), and the fact that project hooks execute inside `root`. These are consequential behavioral traits an agent cannot infer from readOnlyHint=false / destructiveHint=false.

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 primary action and only ~60 words, with zero filler. It is, however, a single semicolon-chained sentence packing four nested conditions, which makes it denser to parse than necessary; a short bullet of preconditions would read better.

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

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

Output schema exists so return values need not be explained, and the description covers the operation's preconditions, side effects and the backward-move exception. For a non-destructive, non-open-world state-transition tool with 100% schema coverage, nothing an agent needs before invoking it 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 baseline is 3, but the description adds genuine meaning: it explains the `to`/`reason` pairing and that a backward move requires `by: owner`, i.e. the cross-parameter constraint the schema only hints at per-property. It does not explain `feature` identifier forms or `root` semantics beyond what the schema already says.

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

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

States a specific verb and resource ('Move a spec-loop feature to the next phase of the schema') and even names the governing artifact (spec/spec-loop.json). An agent can distinguish this from siblings like status, validate or reconcile because the description defines the phase-transition operation precisely, including the backward-move variant.

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 preconditions for advancing (current phase complete, entry rules satisfied, no pending owner edit, beforeLeave hooks exit 0) and explicit conditions for the backward variant (use with `to`, requires owner, requires reason). The gap is that it never references sibling tools (e.g. use status to check phase, validate to test readiness), so routing between tools is left implicit.

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 annotations declaring a non-readonly but non-destructive and non-open-world operation, the description adds substantive behavior: it applies a JSON Patch, converts reported items into open questions, restores the projection exactly, preserves owner files under .spec-loop/overwritten/<time>/, and records lastVerify. It does not cover failure behavior or what happens when the applied/reported count invariant is violated.

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

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

The purpose is front-loaded and there is no wasted filler. However, it is one long dense sentence, making the many behaviors and the invariant harder to parse than a more structured description would be.

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

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

For a complex mutation tool with six parameters, nested objects, annotations, and an output schema, the description supplies the core flow, preservation path, and count invariant. It still leaves a gap around explicit sibling selection guidance and mismatch/error behavior, so it is not fully complete.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds a meaningful cross-parameter invariant: applied + reported must equal the pending count from diff, and it clarifies that reported items become open questions, which goes beyond the schema text.

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: 'Close a reconciliation of the owner edits of a spec-loop feature', then enumerates applying the JSON Patch, turning reported items into open questions, restoring the projection, and recording lastVerify. It references diff's pending count, but does not explicitly contrast itself with the patch or diff siblings.

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

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

The workflow is only implied through 'pending count from diff', suggesting this tool is used after diff. There is no explicit when-to-use versus when-not-to-use guidance, nor a clear alternative among diff, patch, or validate.

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 (readOnlyHint=false, idempotent=true, destructive=false), the description discloses real side effects: it writes into rendered/ and additionally refreshes the manifest and spec/README.md. It also flags a hard refusal guard. It stops short of describing what the refusal error looks like or how to clear it.

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

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

Two sentences, zero filler, with the primary action and its outputs front-loaded before the refusal caveat. Every clause 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?

An output schema exists, so return values need not be explained, and side effects are covered. The main gap is the unverified-owner-edits state: the description states a blocking condition without pointing at the sibling (reconcile/validate) that resolves it, leaving the agent stuck on refusal.

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. The description adds only an implied notion that `feature` targets a feature.json, and says nothing about the `root` resolution chain, so baseline 3 is correct.

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

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

Names a specific verb (project/render) and resource (a spec-loop feature.json into rendered/), and enumerates the collateral outputs (manifest, spec/README.md). It does not explicitly contrast itself with siblings like validate, diff, or reconcile, so an agent must infer the boundary.

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

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

The clause 'Refuses while owner edits are unverified' is a precondition that implies when not to call, which is useful. However, there is no explicit statement of when to choose render over diff/validate/reconcile, nor which tool resolves the unverified state.

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

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

Annotations already declare readOnlyHint, idempotentHint, non-destructive and closed-world, so safety is covered. The description adds genuine value by noting that completeness is recomputed by validate and alterations by diff against the manifest, clarifying that this tool reports rather than mutates state, but it says nothing about cost, freshness, or failure 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?

One dense sentence with no filler, and the field list is front-loaded. It loses a point for being an ungrammatical fragment whose parenthetical clauses make it slower to parse than a plain declarative sentence would be.

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

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

An output schema exists, so not explaining return values is acceptable, and the annotations cover the safety profile. However, for a read tool with nine siblings, the definition provides no routing guidance and no statement of the actual action, leaving the agent to infer selection.

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%, including the root fallback chain and the accepted forms of the feature identifier, so the schema fully carries parameter meaning. The description mentions 'one spec-loop feature' but adds no syntax or selection detail beyond the schema; baseline 3 applies.

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

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

The description is a noun phrase listing the fields returned (phase, completeness, pending edits, history) rather than a verb+resource statement, so it never says plainly 'report the status of a feature.' It does implicitly distinguish itself from siblings by attributing completeness to validate and alterations to diff, but an agent must infer the actual action.

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

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

There is no explicit when-to-use or when-not-to-use guidance and no mention of the alternatives (validate, diff, phase, features). Usage is only inferable from the read-only, reporting framing of the field list.

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

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

Annotations already declare readOnlyHint, idempotentHint and non-destructive, so safety is covered; the description adds genuinely new behavior: Mermaid artifacts are parsed, svg artifacts are existence- and safety-checked only for stored features, and errors carry JSON pointers. It does not describe error verbosity or failure aggregation, leaving a small 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 dense sentence that front-loads the object of validation before the extra checks. It is efficient, though the run-on structure makes the checks slightly harder to scan than a short bulleted breakdown would.

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

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

With an output schema present, return values need not be explained, and the description covers both input modes and the error-pointer convention. Minor gaps remain around precedence between json and feature and whether multiple errors are returned together.

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 json, root and feature fully, including root resolution precedence. The description only implicitly conveys that json takes precedence over the stored file, adding little beyond the schema's own text; 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 (validate) and precise resources (feature.json or a candidate object) plus the exact check set: schema, phase coverage checks, Mermaid parsing, and svg file existence/safety. No sibling (diff, render, phase, reconcile) shares this verb-and-check profile, so the tool is easy to distinguish.

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?

Clearly delineates two usage modes: a stored feature versus a candidate object passed inline, and notes that the stored-file path adds svg artifact checks. It does not name alternatives or when-not conditions (e.g., reconcile vs validate), so it stops short of full routing guidance.

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