brindley

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

With no annotations, the description carries the full disclosure burden. It does reveal a valuable non-obvious side effect — a blocking question reverts a designed initiative back to draft — but says nothing about permissions, reversibility, or the response shape, leaving substantial behavioral gaps.

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 short sentences, front-loaded with the core action and the most consequential side effect before the parameter hint. Every sentence carries information; nothing is padded.

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

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

For a 4-parameter mutation tool with no annotations, no output schema, and low schema coverage, the description is too thin. It omits the meaning of the required `text` and `collection` parameters and any indication of what the call returns.

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 only 25%, so the description needs to compensate and largely doesn't. It explains the `implementation` flag meaningfully, but `text`, `collection`, and the rest of `ref` semantics remain undocumented in both schema and description.

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?

"Add an open question" gives a specific verb plus resource, and the mention of blocking questions vs. implementation questions carves out scope. It does not explicitly name siblings like resolve_question or questions, so the agent must infer the distinction, but the core purpose is unambiguous.

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 offers one concrete usage rule ("Use implementation=true for questions deliberately left to the implementer") and implies when a blocking question applies. There is no when-not guidance and no explicit alternative tool named, so usage is only partially implied.

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?

readOnlyHint=true already declares the safety profile, so the bar is lower, and the description adds genuinely new behavioral context: the default target set is docs changed vs HEAD when no paths are given. It still omits severity levels, exit/error behavior, and what a failing result looks like.

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 front-loaded sentence plus a parenthetical that defines the rule being enforced, with the default behavior trailing. No filler, though the parenthetical makes the sentence dense.

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-only, one-parameter lint tool the description covers purpose and default scope adequately, but with no output schema it should hint at what a run returns (violation list, counts) and how failures surface. Those gaps keep it at minimum-viable.

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 'paths' parameter has 0% schema description coverage, so the description must compensate. It partially does by explaining the implicit default (docs changed vs HEAD) when paths is omitted, but it never says whether paths are files, directories, or globs.

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 (lint) and resource (project docs), and enumerates exactly what it flags: history phrasing, design debate, and links into initiatives. It is clearly distinct from most siblings (regenerate_readmes, tags, questions), though it does not explicitly distinguish itself from the nearby 'validate' tool.

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

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

The description gives the default invocation scope (docs changed vs HEAD), which implies the normal usage context, but it never states when to reach for this tool over alternatives such as 'validate' or 'regenerate_readmes'. Usage must be inferred.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds return-content context (counts by status, ready count) that no annotation or output schema carries, which is genuinely useful. It does not disclose auth requirements or response format details, so it only modestly exceeds the annotation baseline.

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 tight sentence-fragment with no filler; the key content (scope plus returned fields) is front-loaded. The lack of an explicit verb keeps it just short of ideal, 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?

For a zero-parameter, read-only listing tool with no output schema, the description conveys the returned content but is thin on surrounding context such as ordering, filtering behavior, or how it differs from the 'list' sibling. Adequate for the tool's low complexity, but leaves 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?

The tool takes zero parameters, so there is nothing for the description to document. Baseline 4 applies; no parameter semantics are missing or misleading.

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 the resource (every collection) and enumerates returned content (details, counts by initiative status, number ready), but it uses a noun-phrase fragment with no verb and gives no differentiation from generic siblings like 'list' or 'get'. An agent can guess it retrieves collections, but cannot cleanly separate it from those 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?

There is no when-to-use guidance and no mention of alternatives, despite several plausible siblings ('list', 'get', 'ready', 'create_collection'). The description only states what comes back, not when to choose this tool.

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

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

No annotations are provided, so the description carries the full burden. It usefully discloses the cascading effect ("reports which initiatives became ready") and the mandatory `docs_impact` format, but says nothing about irreversibility, required permissions, or whether completion can be reverted.

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 short sentences, front-loaded with the action, then the hard requirement, then the observable side effect. Every sentence earns its place with no 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 mutation tool with no annotations and no output schema, the description covers the required input and the readiness side effect, but omits the `collection` parameter's role and any auth/irreversibility context. Adequate but with clear 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 coverage is only 33%: `ref` is documented in the schema, `docs_impact` is explained well in the description (required, accepts paths or "none: <reason>"), but `collection` is undocumented in both. The description adds real meaning for one gap but leaves another open.

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?

"Mark an initiative done" states a specific verb and resource, and "Reports which initiatives became ready" clarifies the side effect. It does not, however, distinguish itself from the sibling `set_status`, which plausibly overlaps with marking an initiative done.

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 when-to-use guidance and no mention of alternatives such as `set_status` or `ready`. The agent must infer from the name alone when completion is appropriate versus a plain status change.

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 real behavior: the number is auto-generated by scanning the working tree, worktrees, branches and history, and a non-collection folder path is silently promoted to a collection. That side effect is genuinely useful. However, it says nothing about permissions, whether this writes to disk, or what happens on conflicts.

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 short sentences with the verb and resource front-loaded, and each sentence carries information (auto-numbering, collection promotion). Minor awkwardness in 'coined automatically' but no 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 an 8-parameter mutation tool with no annotations and no output schema, the description is thin: it never says what is returned (the new initiative's number or id?), how to reference the created item afterwards, or how the six undocumented parameters behave. It covers the two most surprising behaviors but leaves the rest of the contract implicit.

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 only 25% (only 'type' and 'collection' are described), so the description must compensate for the six undocumented parameters (goal, tags, owner, related, depends_on, title). It adds semantics for 'collection' ('a folder path that isn't a collection yet is marked as one') and implies no number parameter exists, but leaves the remaining fields entirely unexplained.

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 clear verb+resource: 'Create a new initiative', which the bare name 'create' does not convey. It gestures at differentiation from create_collection via the folder-path/collection sentence, but never names the sibling or clarifies the boundary between creating an initiative and creating a collection.

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

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

No when-to-use or when-not-to-use guidance is given. The agent is left to infer from the sibling list whether this is the right tool versus create_collection or add_question; nothing in the description routes that decision.

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 real side effects: it writes `brindley: 1` plus details into README.md front-matter, creates the folder and README if absent, and returns an AGENTS.md/CLAUDE.md snippet on the first collection. It stops short of idempotency/overwrite behavior and permission needs, but the mutation surface is unusually well described.

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 dense sentences, front-loaded with the core action and effect, followed by scope precondition and the notable return value. No filler, nothing repeated from the schema.

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

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

For a 10-parameter mutation tool with no annotations and no output schema, the description covers the write behavior and the conditional return, but leaves most optional fields (owner, title, summary, agent) and error/idempotency behavior unexplained, so an agent still has 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 70%, so the schema already documents most parameters (name default, path example, docs/link/tags/types). The description only adds that the supplied details land in README.md front-matter ('the given details'), which is a modest gain; it leaves owner, title, summary, and agent unexplained.

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

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

Specific verb+resource: 'Mark a folder as a collection' and it names the concrete artifact written (`brindley: 1` in README.md front-matter). It is distinguishable from update_collection by the 'mark' framing and from generic create, though it never names a sibling explicitly to route the agent.

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?

'Works on a folder that already holds numbered initiative files' is a useful precondition, but there is no when-not guidance, no mention of update_collection as the alternative for an existing collection, and no statement about what happens when the folder is already marked.

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?

readOnlyHint=true already tells the agent this is a safe read. Beyond that, the description discloses the shape of the returned payload — dependency classifications (satisfied/blocking/external/missing), dependants, questions, acceptance criteria — which is genuinely useful given there is no output schema. It stops short of noting failure behavior for a bad ref or any size/rate considerations.

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

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

A single sentence, front-loaded with the core action ('Full detail of one initiative') and then the payload breakdown. The parenthetical list is dense but every item earns its place by describing distinct returned data.

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 readOnlyHint and no output schema, the description adequately covers what is returned, which is the main risk. It leaves two gaps: the undocumented 'collection' parameter and no indication of what happens when the ref cannot be resolved.

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 only 50%: 'ref' is documented with its accepted forms, but 'collection' has no description anywhere. The description adds nothing about either parameter — no mention of the ref format or how 'collection' interacts with a bare-number ref — so it fails to 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 gives a specific resource ('one initiative') and enumerates exactly what comes back — dependency report with four classifications, dependants, open questions, acceptance criteria. That is far more than the bare name 'get' conveys. It does not, however, distinguish itself from siblings like 'list', 'graph', or 'ready', so the agent must infer that this is the single-item detail fetch.

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 statement and no sibling is named as an alternative. The phrase 'one initiative' weakly implies this is the single-item counterpart to 'list', but the agent gets no guidance on when to prefer 'get' over 'graph' or 'questions' for the same underlying data.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds useful context by disclosing the return shape (adjacency list plus Mermaid), but says nothing about the effect of include_done, whether the modes can be combined, or the size/limit of the graph returned.

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 the output format front-loaded before the scoping options. Nothing is wasted, though the telegraphic phrasing ('one initiative's neighbourhood') leans on jargon the agent must infer.

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 carrying the return format is valuable, but with four parameters and no required ones it leaves the caller guessing about mode selection and include_done semantics. Adequate but with real gaps for a multi-mode tool.

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

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

Schema coverage is only 25% — just 'ref' is documented there. The description partially compensates by mapping its three modes onto collection, ref (initiative), and tag (theme), but include_done is left entirely unexplained in both places.

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 the artifact (dependency graph), the two output forms (adjacency list plus Mermaid), and the three scoping modes (collection active work, initiative neighbourhood, tag across collections). That is enough to separate it from siblings like list or ready, though the description never states the verb explicitly.

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 three modes imply when you would reach for this tool, but there is no explicit 'use this instead of X' routing, no statement about whether the modes are mutually exclusive, and no guidance on which sibling to pick for plain listing versus graph traversal.

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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the useful return-scope rule (whole root unless `collection` is given), but says nothing about pagination, result ordering, or volume, which matters for an unbounded 'list'.

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 tight sentence with the scope rule front-loaded ahead of the filtering note. Efficient, though the parenthetical is slightly dense given how little it actually specifies.

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

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

For a 6-parameter, zero-required, zero-coverage tool with no output schema, the description is too thin — an agent cannot tell what the filters mean, what the default return shape is, or how results are bounded.

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 0% across 6 parameters, so the description carries the full burden and largely fails: only `collection` is named, and 'optionally filtered' vaguely gestures at tag/type/owner/ready/status without explaining what values they accept or how they combine.

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 ('List initiatives') and clarifies the scope boundary (whole root unless `collection` is given), which compensates for the bare tool name 'list'. It does not differentiate itself from siblings like `collections`, `get`, or `ready`, which could also surface initiative-like data.

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 when-to-use guidance relative to the many sibling tools; 'optionally filtered' hints that filters exist but never says when to prefer this over `collections` or `get`. Only the `collection` scoping rule is stated, and that is behavioral rather than usage selection.

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, so the safety profile is covered. The description adds useful behavior beyond that — cursor-based traversal via `after` and a 'count remaining' in the response — but omits what happens when no unresolved questions remain (null, empty, or error).

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 core resource front-loaded and the cursor semantics immediately following. 'Drives the design-review conversation' is mildly editorial but earns its place by signaling intent.

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 no output schema, the description carries the burden of return-value explanation; it gestures at the shape ('with the count remaining') but doesn't specify fields or terminal behavior. Combined with an undocumented `collection` parameter, it is adequate but not complete for a 3-parameter tool.

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

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

Schema coverage is only 33%; only `ref` is documented. The description partially compensates by explaining `after` as a continuation cursor ('after `after`, if given'), but `collection` is left entirely undefined in both schema and description, so the gap is only half filled.

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 resource and scope: the next unresolved blocking question in one initiative, with a cursor parameter named. It is clearly distinguishable from add_question/resolve_question/questions by the 'unresolved blocking' qualifier, though the verb ('returns') is only implied.

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?

'Drives the design-review conversation' plus the `after` cursor imply an iterative walk through pending questions, but there is no explicit when-to-use versus siblings like `questions` (full list) or `resolve_question`. Usage is inferable rather than 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?

readOnlyHint=true already tells the agent this is a safe read. The description adds the two behavioral facts that matter — results are filtered to unresolved questions and grouped by initiative — but says nothing about ordering, pagination, or what happens when no initiative is supplied.

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 short sentence with no filler, and the scoping constraint leads. It is arguably too terse for a three-parameter tool, but nothing in it 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?

For a three-parameter tool with 33% schema coverage and no output schema, the description leaves key questions unanswered: what include_implementation changes, how ref and collection interact, and what the grouped output looks like. Read-only annotations cover safety only, not the retrieval semantics.

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 only 33%: 'ref' is documented, but 'collection' and 'include_implementation' have no descriptions anywhere. The phrase 'grouped by initiative' loosely maps to 'ref', but the description does not explain include_implementation (the least self-evident parameter) or the relationship between ref and collection, so it fails to 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?

States the specific resource and scope: 'Unresolved open questions, grouped by initiative.' An agent can distinguish this from siblings like next_question, add_question, and resolve_question, which act on single questions. It omits an explicit verb (list/retrieve), so it is clear but not maximally crisp.

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

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

No when-to-use guidance and no mention of alternatives. With siblings such as next_question and resolve_question operating on the same domain, the agent gets no help deciding when to call this aggregate view instead.

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, so the safe-read profile is covered. The description does add genuine behavioral context beyond the annotation: results are only unblocked initiatives and they are returned in prerequisite order, which affects how the agent consumes them. It says nothing about filtering, pagination, or result volume.

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 sentence, front-loaded with the resource and immediately qualified by the actionable-scope clause and ordering. There is no padding, though the em-dash construction is slightly denser than 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?

A read-only query tool with two entirely undocumented parameters and no output schema. The description should at minimum explain what 'type' and 'collection' filter and hint at the shape of the returned list; as written, an agent has to guess on both inputs and outputs.

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 0% and there are two parameters ('type' and 'collection'), yet the description mentions neither. It provides no syntax, allowed values, or meaning for either filter, so an agent cannot know whether these narrow the results or how to supply them.

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

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

The description states a specific resource (unblocked initiatives) and the ordering (prerequisites first), making it clear this returns work that is currently actionable. However, there is no explicit verb and it never names or contrasts itself with plausible siblings like 'list', 'graph', or 'next_question'. The phrase 'designed with nothing blocking' is slightly ambiguous, but the parenthetical 'what an agent can pick up now' resolves 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?

Usage is implied by 'what an agent can pick up now', which tells the agent this is the tool for finding actionable work. It does not state when NOT to use it, nor does it point to alternatives such as 'list' (all items) or 'next_question', leaving the routing decision 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, the description must carry the full burden. It usefully discloses that the default mode mutates generated blocks while check=true is a non-destructive report, but says nothing about what existing content is overwritten, permissions, or whether the blocks are delimited/safe.

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

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

Two compact sentences, no filler, with the core action front-loaded and the mode switch immediately after. 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?

For a 2-param mutation tool with no annotations and no output schema, the description covers the primary action and the check mode but omits the collection parameter's meaning and hints about the return/state change of a rebuild.

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 0%, so the description must compensate. It explains check well (reports stale content, CI-oriented), but the 'collection' parameter is completely undocumented in both schema and description, leaving half the surface unexplained.

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 (Rebuild) and resource (generated README blocks), and specifies what those blocks are (tables + Mermaid). It is distinct from generic siblings, though it does not explicitly differentiate itself from the similarly named check_docs sibling.

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 parenthetical '(for CI)' and 'check=true only reports what is stale' communicate the intended CI usage of the check mode, but there is no guidance on when to run the rebuild at all or how it relates to siblings like check_docs/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?

With no annotations, the description carries the full burden. It usefully discloses the destructive behavior of the default remove mode ("delete it") and the tick format, which is meaningful behavioral context. But it omits permission requirements, behavior when ref is invalid, and the role of index/match/collection.

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

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

Two compact sentences with the default behavior front-loaded before the alternative. Nearly every clause earns its place, though the tick-format example is slightly cryptic.

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 7-parameter tool with no annotations, no output schema, and very low schema coverage, the description covers the core modes but is incomplete on ref selection semantics (index/match/collection) and edge cases. Adequate but with clear 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 coverage is only 14% (just ref documented), so the description must compensate. It adds meaning for mode, record_in (with default and example), and implies answer, but leaves index, match, and collection entirely unexplained in both schema and description.

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+resource ("Resolve an open question") and elaborates the two resolution modes. It is clear what the tool does, but it doesn't explicitly differentiate itself from siblings like questions, next_question, or add_question.

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 explains the default mode ("remove") and the alternative ("tick"), which is genuine usage guidance for mode selection. However, it gives no guidance on when to use this tool versus sibling question-management tools, so routing is only implied.

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 behavioral burden, and it does disclose two meaningful traits: it refuses unknown initiatives (input validation) and refuses cycles (graph constraint). However, it says nothing about idempotency, what happens to existing dependencies not listed, permission requirements, or whether removals of non-existent entries error.

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 core action is front-loaded, and the constraint clause is a compact second sentence that 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?

For a 6-parameter mutation tool with no annotations, no output schema, and very low schema coverage, the description covers the relation-type semantics and two failure modes but omits the `collection` parameter's role and any return/confirmation behavior. Adequate but with clear gaps for a tool of this complexity.

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 only 17% (just `ref`), so the description must compensate. It helpfully maps the parameter groups conceptually: add/remove correspond to blocking `depends_on`, and related_add/related_remove to non-blocking `related`. But it leaves `collection` and the required `ref` semantics unexplained beyond the schema, so the compensation is partial.

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 pair (add/remove) and the resource it manipulates, distinguishing the two relation types by their semantics: `depends_on` is blocking and `related` is non-blocking. Sibling tools are largely unrelated (collections, questions, docs), so explicit differentiation isn't needed, though the description never names the target entity as 'initiatives' until the refusal clause.

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 guidance, no mention of alternatives, and no stated prerequisites for calling it. Usage must be inferred entirely from the verb 'add or remove'.

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 behavioral burden. It usefully discloses lifecycle gating rules, but says nothing about what happens when a precondition fails, what `force` overrides, whether the change is reversible, or what the call returns.

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 compact sentence with the core action front-loaded and the lifecycle constraints appended. It is efficient, though the packed clause structure makes the prerequisites slightly hard to parse.

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 5-parameter mutation tool with no annotations and no output schema, the description covers only the lifecycle gates. The undocumented parameters (`force`, `superseded_by`, `collection`) and failure/return behavior leave meaningful gaps an agent must guess at.

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 only 40%: `force`, `collection`, and `superseded_by` are undocumented. The description does not compensate at all for those gaps, nor does it clarify the accepted status values or aliases beyond restating the lifecycle gates.

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 ("Change status") and adds the distinguishing note that lifecycle rules are enforced. It partially separates itself from siblings by pointing "done" at `complete`, though it never names what entity the status belongs to (initiatives are only implied via the `ref` schema text).

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 concrete preconditions ("designed needs no blocking open questions; in-progress needs ready") and an explicit alternative for one case ("done goes through `complete`"). It lacks any when-not guidance for the other statuses such as deferred, abandoned, or superseded.

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?

readOnlyHint=true already tells the agent this is a safe read with no side effects. The description adds useful return-shape context (unused declared tags are included, counts are broken down by status), but says nothing about ordering, pagination, or size limits.

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 resource and the scope distinction (in-use vs declared-but-unused). No filler, no repetition of the tool name.

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

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

For a zero-parameter, read-only inventory tool with no output schema, the description covers what is returned and the notable inclusion of unused tags. It could be more complete by describing the structure of the per-tag descriptions and counts.

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 tool takes zero parameters, so the schema carries nothing to clarify and the baseline is 4. The description correctly conveys that no filtering input is expected.

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 resource (tags/themes) and its exact scope: every tag in use plus declared-but-unused ones, with descriptions and counts by status. An agent can tell what it retrieves, though the verb is implicit and it doesn't explicitly contrast itself with the sibling 'list' tool.

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

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

There is no when-to-use statement, no prerequisites, and no mention of alternatives among siblings such as 'list' or 'collections'. The usage is only implied by the inventory-like scope.

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

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

No annotations are provided, so the description carries the full behavioral burden for a mutation tool. It discloses the immutability of number/filename, but says nothing about permissions, whether omitted fields are preserved or cleared, whether a section replacement destroys existing content, or what the response returns.

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 capability front-loaded and the hard constraint trailing as a scoping boundary. Every clause adds information an agent needs; 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?

A 10-parameter mutation tool with no annotations, no output schema, and 10% parameter coverage needs far more than two sentences. The description omits parameter semantics, mutation behavior, and error/permission conditions that an agent must know before invoking it safely.

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?

With only 10% schema description coverage across 10 parameters, the description does useful work by grouping fields into categories (front-matter fields, H1, named body section) and clarifying that ref is the immutable identifier. However, most parameters (docs, tags, type, owner, collection, status_note) are never explained, leaving substantial gaps.

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 verb (Edit/replace) and a specific resource (an initiative's front-matter fields, H1, or named body section), which lets an agent separate it from generic siblings like update_collection or set_status. It stops short of explicitly contrasting itself with those siblings, so it lands at 4 rather than 5.

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

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

The description implies when to use it (editing existing initiative metadata or body sections) and states one exclusion (cannot change number or filename), but names no alternative tool and gives no prerequisite or context conditions. That is implied usage rather than explicit guidance.

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 are empty, so the description carries the full burden. 'Edit' implies mutation, but nothing is said about permissions, whether unspecified fields are preserved or cleared, whether the change is reversible, or what happens to fields not listed. The status enum it quotes is already present in the schema, so it adds no behavioral disclosure.

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 tight sentence with no padding, and the resource is front-loaded. It is efficient, though arguably under-specified rather than genuinely concise given the tool's breadth.

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?

A 10-parameter mutation tool with no annotations, no output schema, and incomplete schema coverage needs considerably more than a single clause. Partial-update semantics and the relationship to set_status/update are the most important missing pieces.

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 only 60% across 10 parameters, and the description mentions just one (status), whose enum values the schema already documents. The nine remaining parameters (docs, link, tags, agent, owner, title, types, summary) get no explanation beyond their inline schema text, and the undocumented ones get nothing at all.

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: 'Edit a collection README's details.' An agent can tell it edits an existing collection rather than creating one. It does not, however, differentiate itself from the sibling set_status, which appears to also modify status, or from update.

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

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

No when-to-use guidance at all. The description never says when to prefer this tool over set_status (for status changes) or update, both of which are plausible siblings for the same target resource. Usage must be inferred entirely from the name.

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 establish readOnlyHint=true, so safety is covered; the description goes further by disclosing the return shape (errors and warnings annotated with file and line) and a notable behavior — reporting where a moved file now lives. This is real behavioral context beyond the structured fields, though it stops short of explaining rule severity or scoping 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?

The purpose is front-loaded in the first clause, followed by a dense but non-redundant enumeration of check categories and one sentence on the return value. The long comma-separated list is information-dense rather than padded, though it is a single heavy sentence.

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-only linter with three optional parameters and no output schema, the description covers what is inspected and what comes back (errors/warnings with file and line). Missing only parameter-level scoping detail, which the schema partially supplies.

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 67%, so the schema documents most parameters (docs, rules with examples, collection). The description's rule list loosely maps onto the rules parameter but adds no syntax or semantics for collection scoping or the docs flag, so it neither compensates for the gap nor meaningfully enriches what the schema provides.

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

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

The description states a specific verb and resource ("Check initiatives and collection structure") and enumerates the exact defect classes it detects, so an agent knows it is a structural linter. However, the generic name "validate" and the absence of any reference to the sibling check_docs (which overlaps given the docs flag) leave some ambiguity about which validation tool to pick.

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 describes what is checked but never says when to run it, when not to, or how it relates to alternatives such as check_docs. An agent must infer the usage context (e.g. pre-commit hygiene) from the check list alone.

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