brindley

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: a warning when the text looks like multiple questions and the side effect that a blocking question moves a designed initiative back to draft. However, it never explains how a question is determined to be 'blocking' (no matching parameter exists) and says nothing about the return value or failure modes.

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 side-effect, with no filler. The parenthetical could be trimmed but overall it is dense and efficient.

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 with no annotations and no output schema, the description covers behavior and one flag but leaves 'collection' and 'text' semantics undocumented and the blocking mechanism ambiguous. 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 description coverage is only 25% (ref documented; text, collection, implementation bare). The description compensates for implementation=true, but 'collection' and the required 'text' parameter remain unexplained, so the gap is only partly closed.

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 ('Add an open question') with an added constraint (one decision per question). It is clearly distinct from resolve_question and split_question, but it does not name or contrast with those siblings 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?

Gives concrete conditional usage ('pose several as separate questions', 'Use implementation=true for questions deliberately left to the implementer'), which tells the agent how to frame the call. It stops short of stating when to prefer this over split_question or resolve_question.

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 does so well: it discloses atomic all-or-nothing semantics ("if any fails, nothing is written and every failure is returned"), the validation pass, and the dry-run preview. It also states what is reported back (`milestones`), which is exactly the kind of trait annotations would otherwise 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?

Dense but front-loaded — the batch purpose leads, then field semantics, then failure/dry-run behavior. Every sentence contributes, though the trailing milestone sentence sits a little awkwardly after the atomicity guarantee.

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?

No output schema exists, yet the description explains the return surface (failures list, dry-run preview, milestone reporting) and the mutation contract. It stops short of stating permission/auth prerequisites or how large a batch may be, but is otherwise complete for a batch mutation 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 0%, so the description must compensate, and it enumerates the entry fields (status, reason, type, owner, tags, status_note, docs, dimensions) plus the `status: "from-text"` special value and the dry_run effect. It omits the `collection` field present in the schema, so it doesn't fully close the 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 a specific verb+resource+scope: "Apply update-style changes to many initiatives (tickets/issues) in one call." The "many ... in one call" framing cleanly separates it from the single-item `update` sibling without needing the schema.

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

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

Gives a concrete usage context ("recording statuses across an adopted folder") and routes preview behavior through `dry_run: true`. However it never explicitly names when to prefer `update` over `batch_update`, so the single-vs-batch boundary 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?

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?

Annotations already declare readOnlyHint=true, so safety is covered; the description goes beyond that by disclosing the checks performed and, crucially, the meaning of the result (`ready: false` → stop and report). It does not discuss permissions, cost, or failure modes, but it adds genuine behavioral context.

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 as a direct question, followed by the enumeration of checks and the actionable failure rule. Three sentences, no filler, and the most decision-relevant information (stop on `ready: false`) is placed last for emphasis without burying the purpose.

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 carries the burden of describing returns; it does so partially by naming the fields checked and the key `ready` flag semantics. The undocumented `collection` parameter and the absence of detail on the full response shape leave a small gap, but an agent has enough to call and interpret the 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 50%: `ref` is documented in the schema and echoed by the description's gloss of 'initiative (ticket/issue)', but `collection` is undocumented in both places and the description offers no clarification. With half the parameters covered, the description neither compensates nor regresses, so a baseline 3 fits.

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+resource: it answers whether an initiative is complete and ready, and enumerates the preflight checks it performs (status, dependencies, open questions, acceptance criteria, validation errors). This is far more concrete than a restated name, though it does not explicitly contrast itself with siblings like `ready` or `validate`, which sound adjacent.

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 establishes usage context ('the preflight the implement and spike briefs start with') and gives one explicit decision rule: `ready: false` means stop and report, don't start. However, it never names an alternative tool or a when-not condition, so the agent must infer how this differs from `ready` and `validate` in the sibling set.

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

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

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 two side effects (reports initiatives that became ready and any milestone reached) and the required docs_impact obligation, but says nothing about permissions, reversibility, or failure modes 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 compact sentences with the core action front-loaded and the requirement emphasized early. Every clause earns its place; only minor polish would push it higher.

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 key inputs' obligation and describes the observable results (ready initiatives, milestones). It stops just short of permission/error context but is sufficient to invoke 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 coverage is 67%, so ref and docs_impact are largely documented already. The description reinforces that docs_impact is required and accepts 'none: <reason>', but the 'collection' parameter remains undocumented in both schema and description. Baseline 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?

States a specific verb and resource: 'Mark an initiative (ticket/issue) done — "close" it.' The parenthetical clarifies the domain object, which helps disambiguate from generic siblings. It is clear but does not explicitly contrast itself with the nearby 'set_status' or 'update' 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?

Implied usage is clear (finishing an initiative) and it adds a real conditional rule — docs_impact is required except for spikes. But it gives no explicit when-to-use-vs-alternatives guidance relative to set_status, batch_update, or update, leaving the agent to infer the boundary.

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 does disclose non-obvious behavior: the number is auto-coined by scanning the working tree, other worktrees, branches and history; a folder path is promoted to a collection; milestone changes are reported. It omits write side effects, permissions, and failure modes, but the disclosed behavior is substantively more than the empty annotation set provides.

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 sentences, front-loaded with the verb+resource, and no filler. The milestone sentence is slightly tangential to creation but does convey return behavior, so it 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 9-parameter mutation tool with no annotations and no output schema, the description is only partially sufficient: it explains numbering and milestone reporting, but leaves the majority of parameters and any error/write semantics unexplained. 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 description coverage is 56% and the description adds almost nothing about the 9 parameters — it never explains why, goal, tags, type, owner, related, or depends_on. The only parameter-adjacent statement ('a folder path that isn't a collection yet is marked as one') loosely maps to collection but does not compensate for the undocumented half of the schema.

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

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

States a specific verb and resource: 'Create a new initiative (ticket/issue)', which cleanly separates it from the sibling create_collection. It does not, however, explicitly name or contrast with that sibling, so it stops just short of full differentiation.

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, and no alternatives (create_collection, batch_update) are named. The agent must infer that this is the ticket-creation entry point purely from the phrase 'ticket/issue'.

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 load and does a good job: it discloses the mutation target (README.md front-matter), the creation side effect ('creating the folder and README if needed'), and a conditional output behavior (agent-instructions snippet on the first collection in a repo). It omits idempotency and what happens if the folder is already a collection, which is the main remaining 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?

Three sentences, front-loaded with the core mutation and its target, then the precondition and the conditional return. Every sentence carries information; sizing is appropriate for the complexity.

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 17-parameter, nested-object creation tool with no output schema and no annotations, the description covers the central write behavior and one noteworthy return case, but leaves error/idempotency behavior and the relationship to sibling tools like update_collection unaddressed.

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 82%, so the schema already documents nearly all 17 parameters in detail. The description references 'the given details' generically and adds no per-parameter meaning beyond what the schema fields already state, which matches the baseline-3 case when structured data does the heavy lifting.

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

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

States a specific verb and resource ('Mark a folder as a collection') and describes the exact mechanism: writing `brindley: 1` plus details into README.md front-matter. It is distinct from a generic 'create', though it never explicitly names which sibling to prefer for modification (e.g., update_collection) or for creating initiative files.

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

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

Provides one precondition -- 'Works on a folder that already holds numbered initiative files' -- which implies when the tool applies, but offers no explicit when-not guidance and does not point to alternatives like update_collection or rename_collection for an existing collection.

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 one genuinely useful behavioral fact — that omitting both scoping parameters returns data for every collection — but says nothing about output size, pagination, or cost of the broad default, leaving the caller to infer why scoping matters.

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

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

Two sentences, front-loaded with the resource and its contents before the scoping rule. The enumeration is dense but each listed item (aliases, defaults, required flags) is distinct information rather than padding.

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

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

For a read-only introspection tool with no output schema and two optional parameters, the description covers what is returned and how scoping works. The only real gap is that the caller is not told what the broad no-argument default returns in practical terms.

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 50%: `ref` is documented in the schema, but `collection` is not. The description compensates by defining the scoping relationship between the two parameters and clarifying that supplying neither broadens the result to all collections, which is meaning the schema alone does not convey.

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 resource ('every front-matter field an initiative can have') and enumerates exactly what is returned: statuses and aliases, types, tags, scoring dimensions with defaults/required flags, and free-text fields. An agent can distinguish this metadata-discovery tool from mutation siblings like create/update/set_status without opening a schema.

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

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

It explains how to scope the call ('Give a `collection` or an initiative `ref`; with neither, every collection') but gives no explicit when-to-use guidance relative to sibling discovery tools such as `collections`, `tags`, or `questions`. Usage is implied by the resource it describes 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?

With no annotations, the description carries the full burden and does so well: it discloses that edits are in place, that files are never renamed or moved, that ambiguous cases are withheld into `unfixed`, and that the default is a non-mutating dry run. It even describes the dry-run return payload (file, line, before, after).

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 purpose and scope in the first clause, followed by the exclusion/alternative mapping and dry-run semantics. Dense but every sentence is load-bearing; the parenthetical output description is slightly packed but justified.

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?

No output schema or annotations, yet the description covers return shape, mutation semantics, and scope limits well. The one real gap is the unexplained `collection` parameter, which an agent needs to scope a run.

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 thoroughly explains dry_run (default true, false to write) but never mentions the `collection` parameter at all, leaving half of the two parameters undocumented in both schema and prose.

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 (repair) and resource (validate findings), and enumerates the exact two fix categories it handles: broken links matching exactly one initiative, and depends_on/related front-matter. It also names the sibling tools it is not (repad for padding, renumber for numbers), so an agent can separate it from them without reading schemas.

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

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

Explicitly routes non-matching issue types to alternatives (padding to repad, numbers to renumber) and ties invocation to validate findings. It also states the default operating mode (dry run) and how to actually commit (dry_run: false), which is the key usage 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?

The readOnlyHint annotation already establishes this is a safe read operation. The description adds useful behavioral detail about what is returned: a dependency report with per-dependency classification (satisfied/blocking/external/missing), dependants, open questions, and acceptance criteria. It doesn't mention error behavior when ref is not found, but the enrichment of return content is a meaningful addition beyond the annotation.

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 tightly-packed sentence with zero waste, front-loading the primary purpose and then enumerating return content. Nothing to trim.

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 detail tool with no output schema, the description gives a helpful inventory of returned fields, which is valuable. However, it doesn't address the undocumented 'collection' parameter, error cases, or how this differs from sibling read tools like report/graph. 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 50%. The 'ref' parameter is well-documented in the schema (formats: 'collection#n', bare number, or path) and the description's parenthetical '(ticket/issue)' reinforces that. The 'collection' parameter has no documentation in either schema or description, leaving a gap the description does not compensate for. Baseline 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?

States a specific verb+resource: 'Full detail of one initiative (ticket/issue).' The term 'get' plus the enumerated detail fields make the purpose clear. It doesn't explicitly differentiate from siblings like 'report' or 'fields', but the resource and output focus are specific enough.

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, no named alternatives, no mention of prerequisites. With 33 sibling tools including report, fields, ready, and graph (which also return initiative data), the description does not help the agent choose among them.

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. The description adds genuine context by disclosing the return shape (adjacency list plus Mermaid), which the annotations do not. It stops there – no mention of how 'active work' is determined, graph size limits, or cost of the richer modes.

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 with the resource and output forms front-loaded, followed by the scope options. Nearly every clause earns its place, though the '(theme)' interjection is slightly redundant against the schema's tag field.

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 11-parameter read-only tool with no output schema, the description adequately covers what the tool produces and its three entry modes, and the schema documents the individual flags. It is a bit thin on defaults and on how the adjacency-list/Mermaid output is structured in the response.

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 73%, so the schema carries most of the load. The description loosely maps ref to 'one initiative's neighbourhood' and tag to 'a tag (theme) across collections', but adds no meaning for the many boolean flags (external, related, milestones, include_done) or the arrows/direction semantics.

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

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

States a specific resource (dependency graph) and output forms (adjacency list plus Mermaid), plus three distinct scoping modes. It distinguishes itself from generic siblings like list/get but never names an alternative 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 clauses ('a collection's active work', 'one initiative's neighbourhood', 'a tag across collections') imply which inputs map to which scope, giving some usage context. But there is no when-to-use vs alternatives guidance or any exclusion relative to siblings like list, tags, or get.

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. It discloses genuinely non-obvious behavior — gitignore matching semantics and 'Ignored numbers are still never reused' — which an agent could not infer. It omits permission requirements, error behavior, and whether removing a non-existent pattern fails, leaving meaningful gaps 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?

Purpose is front-loaded, followed by matching semantics, then the dry_run hint and the never-reused note. The pattern-syntax enumeration is dense but each clause carries needed meaning; no filler sentences. Slightly compressed but efficient.

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 and no annotations, the description must stand alone. It covers pattern semantics, dry_run, and a key invariant, which is solid for a config tool, but says nothing about available collections, error handling, or result shape when previewing.

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 `collection` is documented), so the description must compensate, and it largely does: it explains the pattern syntax that applies to `add`/`remove` entries (`#`, `!`, `/` anchoring, trailing `/`, depth rules) and the role of `dry_run`. Only `collection` is left to the schema.

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

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

The description opens with a specific verb pair and resource: 'Add or remove a collection's `ignore:` patterns', immediately clarified as 'numbered files that are not initiatives'. This is clear despite the vague tool name `ignore`. It does not explicitly distinguish itself from siblings like `create`/`update`/`tidy`, but the domain scoping is precise enough for an agent to place 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?

'Use dry_run to preview which files a change would ignore' is the only usage guidance and it targets dry_run rather than when to reach for this tool over `update` or `tidy`. Usage context is implied by the domain but no alternatives or exclusions are named.

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 readOnlyHint annotation already establishes this as a safe read, so the bar is lower. The description adds the scoping context (whole repo vs a single collection) and that filtering is optional, which is useful, but it omits return shape, pagination, and default ordering 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?

A single front-loaded sentence with no waste, and the parenthetical clarifying 'initiatives = tickets or issues' is genuinely useful. It is compact but arguably too terse given the schema's complexity.

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 list tool with no output schema and only 25% schema coverage, the description is far too thin. An agent gets no sense of what the result set contains, how results are ordered by default, or how the various filters interact.

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% (just `where` and `order_by` are documented); tag, type, owner, ready, status, and collection have no schema descriptions. The description mentions only `collection` and generic filtering, so it fails to compensate for the six undocumented parameters.

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 (List) and resource (initiatives), and usefully disambiguates the domain term by equating it with 'tickets or issues'. It also indicates scope (across the repo or one collection). However, it does not distinguish itself from list-like siblings such as `ready`, `questions`, or `report`.

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

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

The only usage cue is 'optionally filtered', which says nothing about when to choose this tool over `get`, `ready`, `report`, or `questions`. There are no exclusions, prerequisites, or alternative-routing guidance despite a crowded sibling set.

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

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

Annotations only declare readOnlyHint=true, so the safety profile is covered. The description goes well beyond that by disclosing the exact shape of the report (status buckets, counted members, initiatives and included milestones, unconfirmed external members, git-history-derived reach dates), which is genuinely useful behavioral context. It omits cost/performance or auth notes, but the return-content disclosure is substantial.

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

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

Purpose is front-loaded in the first sentence, and the second sentence handles the parameter/scope rule. The first sentence is dense with semicolon-separated payload items, but every clause describes a distinct piece of returned data rather than 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?

There is no output schema, so the description must convey the return shape, and it does so in detail. Combined with the single optional parameter being fully explained, an agent has enough to invoke and interpret the tool, with only cross-tool routing guidance missing.

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

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

Schema description coverage is 0%, so the description carries the burden and does so: it explains that `milestone` is a slug, that omitting it returns every milestone, and that supplying it narrows the result to one milestone plus its members. This meaningfully exceeds the bare `{"type": "string"}` schema.

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

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

The description defines the resource precisely (a milestone = a doc with `milestone: <slug>` front-matter) and enumerates exactly what is reported: reached status, done-vs-counted-members, remaining work, unconfirmed externals, and git-derived reach date. The verb is only implicit (it reads as a listing/report tool), but an agent knows what it will get back. It does not explicitly distinguish itself from siblings like `report` or `graph`.

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

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

It gives clear parameter-level guidance: pass `milestone` (a slug) for a single milestone with its members, omit it for all milestones. However there is no guidance on when to prefer this over sibling reporting tools such as `report` or `collections`, and no stated 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?

Annotations already declare readOnlyHint=true, so safety is covered. The description adds that it returns the remaining count and honors an `after` cursor for paging forward, which is genuinely useful beyond the annotation. It doesn't explain ordering, what makes a question "blocking," or what happens when none remain.

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 core behavior front-loaded. The trailing "Drives the design-review conversation" is mildly promotional but does convey intent, so it earns a 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 cursor-based read tool with no output schema and one-third schema coverage, the description does state the return shape (question + count remaining). However, it omits ordering semantics, the meaning of "unresolved blocking," and terminal behavior when no questions 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 coverage is 33% – `after` and `collection` are undocumented in the schema. The description compensates for `after` ("after `after`, if given") implying cursor semantics, but says nothing about `collection` or how it interacts with `ref`. Partial compensation only.

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: retrieves the next unresolved blocking question within one initiative, plus the remaining count. It is distinguishable from question-related siblings like resolve_question and questions, though it doesn't explicitly name a counterpart. Clear but no explicit sibling routing.

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" hints at the workflow context but gives no explicit when-to-use, when-not-to-use, or alternative (e.g. use `questions` for the full list). Usage is implied, 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?

With readOnlyHint=true already covering the safety profile, the description adds real behavioral context: default filtering excludes abandoned/superseded initiatives because dropping the work settles them, and `ref` can override that exclusion. This is non-obvious filtering behavior an agent would otherwise mispredict.

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, zero filler. The primary behavior (unresolved questions grouped by initiative) is front-loaded, with the exclusion rule and its `ref` override following immediately.

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?

It explains the filtering default but omits what `collection` and `include_implementation` do and gives no hint of the return shape (no output schema exists). Adequate for the read-only query it is, but an agent calling with those two parameters is guessing.

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% — `collection` and `include_implementation` have no descriptions anywhere, and the description does not explain them. It does clarify `ref`'s role (requesting otherwise-excluded initiatives), but two of three parameters remain semantically opaque.

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 resource (open questions) and its grouping (by initiative), which distinguishes it from siblings like next_question, report, and list. The verb is implicit ('returns/lists') rather than stated, but an agent can tell what it retrieves.

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

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

It gives one concrete usage rule: abandoned and superseded initiatives are excluded by default unless requested via `ref`. However, it never says when to use this tool versus next_question or report, nor what the default scope is beyond the exclusion behavior.

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 establishes this is a safe read, so the bar is lower. The description adds ordering semantics ('suggested order, prerequisites first'), which is genuine behavioral value beyond the annotation, but says nothing about scoping, filtering, or result size.

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

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

A single front-loaded sentence that leads with the resource and its defining property. No filler, though it is arguably too terse given the undocumented parameters.

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?

Wait—reassess: for a simple read-only query with an annotation covering safety and no output schema, the description conveys the return concept and ordering adequately. The remaining gap is parameter coverage, which is a schema-side omission as much as a description one.

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% across two parameters (type, collection), and the description never mentions either. With no schema documentation and no compensating text, an agent cannot know what type or collection control.

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 (initiatives/tickets/issues) and a clear scope qualifier ('designed with nothing blocking'), so an agent knows it returns unblocked work. It does not, however, distinguish this from close siblings like check_ready, next_question, or questions.

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 phrase 'what an agent can pick up now' implies the use case—finding available work—but there is no explicit when-to-use guidance or mention of alternatives such as check_ready. 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?

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 and does well: it discloses the link-rewriting side effect, the conditional name change and which reference forms get rewritten versus preserved, explicit refusal conditions (existing destination, nested collection, duplicate name), and what dry_run returns. It omits permission/auth requirements and whether the move is reversible, keeping it from a 5.

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

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

The description is dense but every clause adds a real behavioral fact (link rewriting, name derivation, refusal cases, dry_run), and the core action is front-loaded. It is longer than typical but not 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 3-parameter mutation tool with no annotations and no output schema, the description covers the important semantics: side effects, name-change rules, refusal conditions, and dry-run behavior. The main remaining gap is the meaning of the `collection` identifier and the shape of the dry-run plan.

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 'to' is documented in the schema, leaving `collection` and `dry_run` bare. The description compensates for dry_run ('returns the plan') and implicitly for 'to' via 'destination', but never explains what `collection` accepts, so half the parameters remain ungrounded 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?

States a specific verb and resource ('Move a collection to a new folder') and immediately clarifies that the move also rewrites relative links and may change the collection's name, which explains why a tool named rename_collection actually relocates folders. It does not explicitly contrast itself with siblings like update_collection or create_collection, so it stops short of a 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 usage through its behavioral detail (link rewriting, name-change side effects, refusals) and mentions dry_run, but never states when to choose this tool over update_collection or how to recover from a refusal. Guidance is inferable rather than explicit.

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 burden and does it well: it discloses that the operation renames files/folders, preserves the slug padded to collection width, and rewrites references repo-wide, plus that dry_run returns a plan without writing. It omits permissions, reversibility, and failure modes, keeping it out of 5 territory.

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

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

Purpose and scope are front-loaded, then effects, then the parameter-specific clarifications. Dense but zero filler; each sentence adds distinct information.

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

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

For a mutation tool with no annotations and no output schema, the description covers side effects, the default-value behavior, and the preview mode well. It stops short of describing what the dry_run plan contains or what state the repo is left in on failure.

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 50% (only `to` and `ref` are documented in-schema), so the description must compensate. It explains the default for `to` ('coined as create does'), the path form of `ref` for duplicate pairs, and the semantics of `dry_run`, adding real meaning beyond the schema. `collection` remains 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?

States a specific verb and resource ('Give an initiative a new number') and the exact motivating scenario (fixing a collision after a merge), then enumerates the concrete effects: file rename, asset folder rename, link and '<collection>#<n>' rewrites. This clearly distinguishes it from siblings like rename_collection and repad.

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?

Names a clear trigger ('fixing a number collision after a merge'), gives the disambiguating case for using `ref` as a path when handling one file of a duplicate-number pair, and flags the non-destructive dry_run path. It does not explicitly name sibling alternatives like repad or rename_collection, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden and does so well: it discloses the mutation scope (renames files and their asset folders and rewrites links across the repo), the safety default (dry run returns planned changes), and a failure mode (refuses a width too small for the highest number). It even describes the return payload, compensating for the absent output schema.

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

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

Purpose is front-loaded and the em-dash parentheticals efficiently convey the default width and format. It is dense but every clause earns its place; the multi-clause first sentence is slightly heavy but not wasteful.

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 3-param mutation tool with no annotations and no output schema, the description covers operation, defaults, side effects, return values, and a refusal condition. An agent has everything needed to invoke it correctly and 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?

Schema coverage is only 67% and collection is undocumented there, but the description supplies the two key behaviors: width defaults to the width most files use, and dry_run defaults to true. It adds real meaning beyond the schema, though it doesn't elaborate on the collection argument itself.

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 (pad) and resource (initiative numbers in a collection), with concrete examples of the target format (`01-`, `001-`). It is clearly distinguishable from siblings like renumber and rename_collection without opening any schema.

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

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

Explains the operating mode clearly: dry run by default and dry_run: false to apply, so the agent knows the safe path. However, it never names or contrasts with alternatives (renumber, rename_collection), so the when-versus-which guidance is implied rather than explicit.

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

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

With no annotations at all, the description carries the entire behavioral burden and does well: it discloses the write-to-disk side effect and its default path, states 'Changes no initiative' (safety profile), and declares the return values ('the file's path and the figures'). It omits some operational detail - whether an existing file is overwritten, whether git history is a prerequisite, and cost on large repositories - which keeps it from a 5.

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

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

The action and artifact are front-loaded, and the trailing sentences ('Returns the file's path and the figures. Changes no initiative.') efficiently convey return and safety. The middle em-dash clause enumerating report sections is long but each item is informative rather than 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 tool with no output schema and no annotations, the description covers the essentials: what is produced, where it lands, what it consumes, what it returns, and that it mutates nothing. It leaves some ambiguity about prerequisites (git history availability) and the meaning of domain terms like 'workstreams', so it is strong but not exhaustive.

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 structured fields already document all 8 parameters, including the enum for mode and the palette/branch globs - the baseline is 3. The description does add a little interpretive context by introducing the concept of 'this period' (the since/until window) and the default output location, but nothing that the schema does not already say.

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 and artifact ('Write a one-page progress report ... self-contained HTML file ... build/brindley-report.html') and enumerates the report's contents (headline figures, scope-over-time, delivered/added/removed, workstreams, attention items) plus its inputs (collections + git history). No sibling tool produces a report, and the framing 'for people outside the team' immediately separates it from raw-data siblings like list, collections or graph.

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 context is clear: this is the audience-facing digest ('for people outside the team') built from collections and their git history, as opposed to the raw listing/graph tools. It does not, however, name an explicit alternative or state when not to use it (e.g. large repos, no git history), 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.

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

With no annotations at all, the description carries the full burden and does disclose the key destructive trait: default mode deletes the question, and the decision is written to record_in (default "Decisions"). That is real behavioral context beyond the schema. It omits whether the deletion is reversible and what happens on a failed match.

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 then the mode behaviors. Every sentence carries information. The nested quotes and defaults make it dense and slightly cryptic, but there is 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 7-parameter mutation tool with no annotations, no output schema, and low schema coverage, the description covers the most important behaviors (deletion, default record target, mode semantics). It still leaves index, match, and collection unexplained, so an agent could not confidently invoke every parameter.

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 very low (14%), so the description must compensate, and it does clarify mode, record_in (with default), and the answer concept. It says nothing about index, match, or collection, leaving roughly half the parameters undocumented in both places. Partial compensation warrants a middle score.

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 ("Resolve an open question") that is clearly distinct from siblings like add_question, split_question, and next_question. It also enumerates the two result modes, so an agent knows what the tool produces. It does not explicitly name a sibling it is not, which keeps it just short of a 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 explains what each mode does and flags "remove" as the default, which gives implicit guidance on choosing between them. However, it never states when to prefer "tick" over "remove" or when this tool should be chosen over alternatives in the question lifecycle. Usage is implied rather than prescribed.

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 does so well: it discloses side effects (adds a bullet with relative link and optional why), removal limits (bullets only; paragraph-embedded links are left in place and reported with their line), and error conditions (refuses unknown initiatives and cycles). This is exactly the behavioral context an agent needs for a mutating 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?

Front-loads the core action, then layers the essential distinctions and limits. It is dense with parentheticals and long clauses but nearly every sentence carries behavioral weight, so waste is minimal.

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 mutation tool with no annotations and no output schema, the description covers side effects, partial-failure reporting, and refusal cases thoroughly. The main gap is the undocumented `collection` parameter, which leaves an agent guessing at one input's role.

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 low (29%), so the description must compensate, and it does add meaning for add/remove/why and the related_* semantics via the blocking/non-blocking framing. However, parameters like `collection` and the exact roles of `related_add`/`related_remove` are never explained in prose.

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 and resource: 'Add or remove dependency links,' and immediately defines what a dependency is versus a non-blocking `## Related` link. An agent can tell what the tool operates on, though it never names a sibling alternative to distinguish itself from tools like `update` or `graph`.

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 rather than stated: the Dependencies-vs-Related distinction helps an agent choose the concept, and the bullet-vs-paragraph rule scopes when removal will work. But there is no explicit 'use this instead of X' guidance against the many sibling mutation tools.

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

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

With no annotations present, the description carries the full burden and does disclose real side effects: a callout is added under the title for abandoned/superseded/deferred work and removed on reopen, and milestone impact is surfaced under `milestones`. It stops short of explaining permissions, whether `force` bypasses the lifecycle checks, or reversibility.

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 its lifecycle rules; nothing is filler. The third sentence is long and packs several behaviors together, which costs a little readability but not substance.

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 covers the lifecycle contract, the `reason` requirement, and the visible side effects well. The remaining gap is the unexplained `force` escape hatch and any permission or error behavior, which an agent would need before invoking confidently.

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

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

Schema coverage is 63%, so the schema already documents most parameters including `reason` and `branch`. The description adds the requirement semantics for `reason` (required to abandon, optional to supersede/defer) and the `milestones` reporting behavior, but leaves `force`, `outcome`, `superseded_by`, and `collection` 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?

The description opens with a specific verb+resource ('Change an initiative's status') and immediately scopes it by naming the lifecycle it enforces. It also distinguishes itself from the sibling `complete` by stating 'done goes through `complete`', so an agent can separate this tool from that one without opening either schema.

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

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

It states preconditions that effectively define when the tool may be used (designed needs no blocking open questions; in-progress needs ready) and routes one status to an alternative tool ('done goes through `complete`'). It also flags that abandoning requires a `reason`, which is a hard usage gate.

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

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

With no annotations at all, the description carries the whole burden and does well: it discloses atomicity ("one write"), marker inheritance for parts, that an `answer` settles a part as written, the record_in default of "Decisions", and that it returns the still-open parts with their new indexes. It omits what happens to the original question beyond "in its place", and says nothing about permissions 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?

Purpose is front-loaded in the first clause before the detail, and every sentence carries real information (inheritance rules, answer handling, return value). It is a single dense sentence with stacked parentheticals, which costs some readability but not enough to be wasteful.

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-style tool with no annotations and no output schema, the description covers the important semantics and even states the return value. But five of seven parameters are undocumented (including the whole `match`/`index` targeting mechanism) and the "remove" mode is never explained, leaving real gaps for an agent wiring up the call.

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 low (29%), so the description must compensate, and it does explain the `into` payload shape (text or { text, implementation?, answer? }), inheritance, `record_in` and its default, and the "tick" value of `mode`. However `ref`, `index`, `match`, `collection`, and the "remove" mode value are left entirely to the schema.

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

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

States a specific verb (split) and resource (an open question) plus the exact transformation: one question per decision, in place and order, in one write. It name-drops the sibling resolve_question as the behavioral analogue, so an agent can separate it from add_question or resolve_question without opening a schema.

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

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

The opening clause implies the trigger condition clearly (an open question that poses several decisions), and it points to resolve_question for the tick-mode behavior. There is no explicit when-not-to-use or statement of prerequisites (e.g. permissions on the initiative), 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.

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

Annotations already declare readOnlyHint=true, so safety is covered, but the description adds genuinely useful behavioral context: the result set is a superset that includes declared-but-unused tags (not just active ones), it carries counts by status, and it conditionally includes a theme doc defined by a `theme: <tag>` front-matter convention. That conditional-inclusion rule is a real disclosure the agent would not otherwise know.

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 with the core payload front-loaded and the conditional theme-doc rule tucked into a clarifying parenthetical. No filler, though the run-on structure makes it slightly harder to parse than two short sentences 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?

With no parameters, no output schema, and a read-only annotation, the description carries most of the burden and does so adequately by enumerating the returned content. It omits any mention of result size, ordering, or pagination, which is a minor gap for a potentially unbounded listing.

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 disambiguate; baseline is 4. The description correctly implies a parameterless full listing rather than a filtered query.

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 precisely what the tool surfaces — every tag in use, declared-but-unused tags, descriptions, per-status counts, and the theme overview doc — so the resource and payload are unambiguous. It lacks an explicit verb (implied list/retrieve) and does nothing to distinguish itself from siblings like `fields`, `collections`, or `get`, which an agent could plausibly confuse it with.

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, no prerequisites, and no named alternatives among the many sibling tools. The agent must infer that this is the tag-listing tool purely from the name and payload 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?

With no annotations, the description carries the safety burden well: it discloses the dry-run-by-default posture, exactly what a dry run returns (each move and link rewrite), and how to actually apply (`dry_run: false`). It stops short of stating reversibility, permissions, or error behavior on collections without `folders:`.

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 that lead with scope, then behavior, then the dry-run contract. Em-dash clauses make it slightly heavy, but every sentence contributes needed information.

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

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

For a two-parameter mutation tool with no annotations and no output schema, the description covers the precondition, the effect, the link-rewriting side effect, the dry-run return, and how to commit. Only the collection identifier semantics and failure modes remain unstated.

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%, but the description gives `dry_run` real meaning (default true, pass false to apply). The `collection` parameter is only implicitly characterized as one that declares `folders:` — its identifier format or expected value is not clarified.

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 and effect: move every initiative to the folder matching its status (or the collection top), carry its asset folder, and rewrite links. It also implicitly distinguishes itself from set_status by noting that status changes keep things in step, so tidy is only for files already out of place.

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 clear usage context: it applies to collections declaring `folders:`, is for correcting already-out-of-place files, and the status-change tools handle ongoing alignment. It lacks an explicit named alternative (e.g. `set_status`), so the routing is implied rather than spelled out.

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 present, so the description carries the full burden, and it does disclose meaningful traits: no lifecycle checks, the 'refused if a status is recorded' rule, the H1 replacement and leading-heading-drop behavior, and the milestone reporting side-effect. It stops short of stating permission/auth requirements or reversibility, so it is strong but not exhaustive.

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?

Dense but mostly earned: the core action is front-loaded and each clause adds a real constraint (status recording, set_status alternative, number/filename immutability, milestone reporting). Slightly heavy with backtick asides, keeping it below a clean 5.

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

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

For a 13-parameter mutation tool with no annotations and no output schema, the description covers the highest-risk ambiguities (status vs. set_status, immutability, milestone side-effects) and needs no return-value explanation since output is absent. Leftover gaps are the undocumented front-matter params, which keeps it from a 5.

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

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

Schema coverage is 46%, so several parameters (docs, tags, type, owner, title, collection, status_note) are undocumented in both schema and description. The description clarifies the tricky `status` semantics and the section/content behavior, which is useful, but it does not compensate for the remaining coverage gap, so the baseline holds.

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 (edit) and precise resources: an initiative's front-matter fields, H1, or a named body section. It explicitly contrasts with the set_status sibling and names what cannot be changed (number, filename), so the agent can distinguish it from siblings without opening the schema.

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

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

Gives explicit when-to-use (edit fields, refine done work with no status change) and names the alternative condition ('to change a recorded status, use set_status'). The overlap with set_status is resolved directly in the text.

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 behavioral burden. 'Edit' implies mutation but nothing is said about permissions, whether unlisted fields are preserved, merge-vs-replace semantics for arrays/objects, or the side effects the schema alludes to (status folders moving files). Only the implied write nature is conveyed.

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, front-loaded with the verb and resource, with zero filler. It is efficient but arguably under-specified rather than 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 17-parameter mutation tool with nested objects, no annotations and no output schema, a single sentence is not enough. Key agent-facing facts (partial updates, delete-by-null, file-moving side effects) live only in the schema and are never surfaced at the description level.

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 76%, so the schema already documents most of the 17 parameters, including null-removes behavior and the folder-move side effect. The description repeats the status enum that the schema already enforces and mentions no other parameter, so it adds essentially no semantic value beyond the baseline.

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: editing a collection README's details, and names one editable field (status). It does not distinguish itself from the sibling 'update' or 'set_status' tools, so an agent cannot tell when this is the right entry point versus those.

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. With siblings like 'update', 'set_status', and 'rename_collection' in the list, the description gives no hint about which of these a status change or rename should route through.

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 does: it discloses that the switch persists for the entire session and that every later call reads and writes the new checkout, plus the reversal condition and the return value. This is exactly the side-effect information an agent needs for a stateful, session-mutating 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?

Four short sentences, front-loaded with what the tool does, followed by when to call it in each direction. No filler, and the durable-session constraint is stated first where it matters most.

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

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

For a single-optional-parameter stateful tool with no annotation or output schema support, the description covers purpose, timing, reversal, persistence, and the return value. Nothing needed to invoke it correctly is missing.

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

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

Schema coverage is 100%, so baseline is 3, but the description adds semantics beyond the schema: it explains that passing the original checkout's path is equivalent to omitting path, which the schema's wording does not state. That extra behavioral meaning for the sole parameter earns above baseline.

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 (switch) and resource (this server's git worktree) plus the scope ('of the same repository, for the rest of this session'), which no sibling tool covers. An agent can distinguish it from create/update/tidy without opening the schema.

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

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

Gives explicit timing rules: call it right after creating the worktree so edits land in that branch's commit, and switch back after merging before removing the worktree. Both the when and the sequencing relative to other operations are spelled out.

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.

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 provenance context (version is computed from git tags and Conventional Commits, and a build commit is included), but says nothing else about format, stability, or failure modes.

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

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

A single front-loaded sentence with zero waste; the resource and its contents are stated immediately.

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 parameterless, read-only version endpoint with no output schema, the description conveys enough to call and interpret it: what version means here (git-derived) and that a build commit is included. Only a note on exact return shape would improve it, which is minor.

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 has nothing to document and the description carries no parameter burden. Baseline for a parameterless tool 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 names a specific resource and what it returns: the Brindley server's version plus build commit, and even clarifies provenance (git tags + Conventional Commits). It is clear and unambiguous, though it does not explicitly differentiate itself from adjacent read tools like get or list, which is why it falls short of a 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?

There is no guidance on when to invoke this tool versus siblings such as get, list, check_docs, or report. The reader must infer that it is a diagnostic/informational call; no context or exclusions are provided.

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