List spec-loop features

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.