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

No annotations exist, so the description carries the disclosure burden. It reveals the key consequence that an abandoned item will not resume and stops holding its phase open, which prevents an unfinished task from blocking a phase forever. It does not discuss permissions or reversibility, but the central behavioral difference is clearly disclosed.

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 about three sentences and front-loads the purpose before the usage condition and blocking distinction. Every sentence contributes useful information, and the blocking comparison earns its place because it prevents a likely invocation error.

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

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

For a three-parameter state-change tool with no output schema, the description plus schema explains when to call, what the phase implication is, and how force affects sub-tasks. A minor gap is that it never explicitly says the item remains in the system rather than being deleted, but this is mostly inferable from the 'phase open' phrasing.

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

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

Schema description coverage is 100%, so the baseline is 3. The schema already documents id, force, and reason with meaningful descriptions; the tool description itself adds no parameter-specific semantics beyond 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?

States a specific action ('Stop work') on a specific resource ('an item') and clarifies that it is not completion. The explicit comparison to blocking distinguishes it from a key sibling tool, ddflow_block, without requiring the agent to open 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?

Provides an explicit trigger condition: 'Use when a task turns out to be unnecessary or impossible.' It also gives a clear when-not-to-use rule by contrasting with blocking: blocked items wait and resume, abandoned items do not. This is actionable 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, the description carries the behavioral burden and it does clarify the state transition and rationale ('a blocked item states its reason'). Still, it does not say whether the claim is released, whether blocking is reversible, how the lease is affected, or what the tool returns.

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

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

Two sentences, front-loaded with the core behavior and followed by a crisp rationale. No filler or repetition of the schema.

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

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

The definition is adequate for a simple two-parameter tool, and it explains the purpose and reason format well. However, it omits the practical consequences of blocking (e.g., relation to claim/lease, reversibility, response), which the description itself draws attention to by mentioning lease expiration.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds value by giving concrete examples of what 'reason' should contain ('a missing decision, an upstream outage, a question for the operator'). This helps the agent populate the required 'reason' parameter accurately.

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 and resource: 'Mark an item blocked on something outside the queue'. It also distinguishes this from the 'claimed' state, which is a key sibling alternative, so an agent can tell what this tool does and how it differs.

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 decision context: use when blocked on something external like 'a missing decision, an upstream outage, a question for the operator'. It also implies when not to use it: rather than silently leaving an item claimed. However, it does not explicitly name a sibling tool or list additional exclusion conditions.

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 of disclosing behavioral traits. The phrase 'readable board' hints at a read-only presentation, but the description never explicitly states that the tool does not modify the work queue, what it returns, or whether it performs any computation beyond presenting existing data.

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 a single, efficient sentence with no filler or repetition. It front-loads the core concept ('whole work queue') and adds the distinguishing critical-path detail immediately, making it easy to parse quickly.

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 tool with no output schema and no annotations, the description is too thin to be fully actionable. It explains what the board shows at a high level but does not clarify the output format, confirm that the operation is side-effect-free, or provide enough context to distinguish this tool from the many related workflow-visualization siblings.

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 schema already documents the single 'phase' parameter with a clear description ('Restrict to one phase'), and schema description coverage is 100%. The tool description adds no parameter-level meaning beyond what the schema provides, so the baseline score of 3 applies.

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

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

The description identifies the resource as the 'whole work queue' and the deliverable as a 'readable board' with the critical path, which is specific enough to convey the tool's purpose. However, it lacks an explicit action verb like 'display' or 'show' and does not name or distinguish itself from visually or status-oriented siblings such as ddflow_status, ddflow_workflow, or ddflow_show.

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 only implied by the description: use this when you want the entire work queue presented as a board with the critical path. It provides no explicit when-to-use guidance, no exclusions, and no comparison to alternatives, which is a noticeable gap given the large sibling tool list.

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

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly describes the returned content and notes token efficiency, but it does not explicitly state whether the tool is read-only or whether it has any side effects such as claiming work or updating state.

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

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

The description is two sentences with no wasted words. It front-loads the most important usage instruction ('START HERE every session'), lists the output contents compactly, and closes with a concrete advantage (token savings).

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-style informational tool with no output schema and no annotations, the description explains what the result contains, when to use it, and why it is preferable to reading raw project files. It is slightly jargon-heavy ('budgeted pack'), but the following list disambiguates it well.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters thoroughly. The description adds no parameter-specific detail, but it does not need to because the schema covers item, phase, and check_recovery.

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

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

The description states a specific action ('Returns a budgeted pack') and enumerates exactly what the pack contains: recoverable work, current item, ready-to-start work, blocked items, and relevant lessons. It clearly establishes the tool's role as the session entry point, which distinguishes it from the many sibling ddflow tools.

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 instruction 'START HERE every session' gives explicit when-to-use guidance, and 'Use this INSTEAD of reading the project's lesson or rule files' names the alternative it replaces. It does not explicitly contrast with sibling tools like ddflow_status or ddflow_session_start, which is a minor gap.

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 behavioral disclosure. It does reveal the unusual regression-test requirement and the fail-first workflow. However, it does not state side effects, such as whether the bug becomes permanently closed, whether lesson fields trigger lesson creation, or whether the operation is reversible.

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 compact sentence with the core action front-loaded and the critical requirement stated immediately. The em-dash workflow adds necessary context without wasting words.

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?

The description is sufficient for a basic close with id and regression_test, but it ignores the optional lesson-capture parameters entirely and provides no output or side-effect information. For a mutation tool in a large sibling family, an agent could still call it correctly, but would not understand when to attach lesson data.

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

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

Schema description coverage is 100%, so the schema already documents all five parameters. The description adds some meaning around regression_test ('catch it again') but does not add value for id, lesson, lesson_rule, or lesson_title. This matches the baseline for high schema coverage.

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 clear action ('Close a bug') on a specific resource, distinguishing it from the sibling ddflow_bug_found at least implicitly. It does not explicitly name the sibling or contrast behaviors, so it stops 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?

It gives a clear condition for use: closing requires a regression test, and it explains the expected workflow (write test, watch it fail, then close). It does not explicitly say when not to use it or name alternatives, but the prerequisite is concrete and actionable.

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 disclosure burden. It does convey workflow behavior: reporting first is necessary for a later fix to be accepted, and unrecorded bugs cannot be proven found. However, it does not describe what actually happens when invoked, such as whether a record is created, whether an ID is auto-generated, or what state changes occur. Moderate transparency.

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 core instruction is front-loaded in the first sentence, and the follow-up sentences provide useful context about why reporting first matters. The final analogy is motivational rather than strictly operational, but it reinforces the usage rule without excessive length. Well-structured overall, with minimal waste.

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 simple three-parameter bug-reporting tool with no output schema, the description covers purpose and workflow, and the schema covers parameters. However, with no annotations and no output schema, it leaves some practical context unstated, such as what happens after reporting and whether the agent must supply or track the id. Adequate but not fully complete.

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

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

Schema description coverage is 100%, so the parameters are already documented: id, item, and summary. The description reinforces that summary is the one-line statement of what is wrong, but it does not add new field-level meaning beyond the schema. This meets the baseline for fully covered 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?

The description opens with a specific action ('Report a bug') and names the exact resource (a bug record). It explicitly distinguishes itself from ddflow_bug_fixed by saying this tool is for reporting before fixing, while the sibling refuses to close without a regression test. An agent can clearly tell what this tool is for.

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 is directive about when to use it: 'the moment you find it, BEFORE fixing it.' It also explains the relationship with ddflow_bug_fixed, making it clear that bug_found precedes bug_fixed and is required for accountability. This is explicit usage guidance with a named alternative.

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 of disclosure. It does provide one useful trait: 'Derived from completed work, so there is no state file to drift.' However, it fails to disclose that passing `ran`/`note` records a pass run, which is a mutating behavior an agent needs to know before invoking the 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 short sentences with no filler. The first sentence immediately states the core purpose and gives examples; the second adds a valuable behavioral guarantee. 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?

The query behavior is well described and the schema covers the `ran`/`note` parameters, so the core use case is usable. However, the description does not mention the record/completion mode at all, nor clarify what 'due' means in cadence terms, leaving a moderate gap for a tool with no output schema.

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

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

Schema description coverage is 100%, so the baseline is 3. The description adds meaning by enumerating concrete pass names and the kinds of work the cadence tracks, which helps an agent infer plausible values for `ran` and the context for `note`. It does not map directly to parameters, but the examples are genuinely useful.

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 identifies a specific resource and scope: periodic whole-repo passes that are due, with concrete examples (integration tests, architecture review, mutation testing, dedupe sweep, lessons compression). It is clearly distinct from sibling status/progress tools, though it lacks an explicit verb like 'list' or 'show'.

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 the usage scenario—check which periodic passes are due—but it does not explicitly state when to use this tool versus alternatives or when not to use it. No exclusions or sibling comparisons are provided.

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

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

With no annotations, the description carries the full burden. It discloses refusal behavior (exit 3 on conflicts), the condition for legitimate force, the recording of overrides, and the rationale behind not stealing expired leases. This goes beyond basic operation and covers important side effects and 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 sentences, front-loaded with the core purpose, followed by critical behavioral warnings. Every sentence earns its place, with no fluff. The ALL-CAPS warning is effective for emphasis without being verbose.

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?

Given the tool's complexity (5 params, conflict handling, force semantics) and the absence of an output schema, the description covers the essential behavioral context: refusal conditions, force legitimacy, and the no-steal rule. It does not describe the full lease lifecycle (e.g., what happens on success), but that is likely covered by sibling tools. The schema fills parameter details, making this sufficiently complete.

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

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

The schema covers all 5 parameters with detailed descriptions (100% coverage), so the baseline is 3. The main description adds no parameter-specific meaning, but the schema's descriptions—especially for force—are thorough. The description does not need to repeat what the schema already explains.

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 ('lease') and resource ('an item') plus the concrete action ('create its isolated git worktree'). It is unambiguous and clearly distinguishable from sibling tools like release, recover, or merge, which have different purposes.

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 provides clear usage context: it refuses on conflicts, explains when the force override is legitimate (after ddflow_recover), and warns against stealing expired leases. It does not explicitly name alternatives, but the force description references ddflow_recover, giving conditional guidance. This is sufficient for an agent to decide when to call it.

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

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

With no annotations to rely on, the description carries the full disclosure burden and succeeds: it reveals that apply=true removes merged worktrees/branches, lands commits for queue-done items, and that dirty trees are never modified regardless of apply. This goes well beyond the schema by detailing side effects and the key safety boundary.

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 sentences, each earning its place: classification categories, default report mode, apply behavior, and the dirty-tree safety warning. The most important information is front-loaded, and there is no filler or repetition of the schema.

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

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

The description gives a full picture for a one-parameter tool with no output schema: categories, default behavior, apply semantics, and a critical safety exception. Minor gaps remain — 'orphan' and 'stale branch' are not formally defined, and 'lands commits' references an internal queue concept — but these do not prevent an agent from invoking the tool correctly or understanding its effects.

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 schema already describes apply as 'Perform the safe actions' with 100% coverage, so the baseline is 3. The description adds value by explaining what those safe actions actually are (removing merged items and landing done commits) and by clarifying that the default is a report-only run when apply is not true. This is useful enrichment beyond the schema.

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

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

The description names a specific action (classify every ddflow worktree and branch), enumerates the classification categories (merged, unmerged, dirty, orphan, stale), and states the two operational modes: report by default and remove with apply=true. This clearly differentiates it from sibling tools as a cleanup/analysis utility.

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 clearly states the default behavior (reports) and when to use apply=true to perform removals, plus an explicit exclusion: dirty trees are never touched automatically. It does not name alternative sibling tools or state when NOT to use this tool in favor of another, but the usage context is still clear for an agent.

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 provided, the description carries the full behavioral burden and meets it well. It explicitly states the tool is read-only, that it detects and advises rather than installs, and it explains what exit 2 means, which is critical for interpreting invocation results.

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 front-loaded with the tool's purpose, and each subsequent sentence earns its place by explaining gate semantics, the no-companion implication, exit-code meaning, and read-only behavior. There is no filler, repetition, or vague 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 tool with no required parameters and no output schema, the description provides strong context: what it reports, the domain rules around gates, and a key error condition. It falls just short of perfect because it does not sketch the expected result structure or what a healthy versus unhealthy companion setup looks like beyond exit 2.

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 schema already fully documents the single parameter no_probe with 'Skip the detection probes (faster, less certain)', so the description does not need to add much. The description's detection language aligns with the parameter, but adds no new semantic detail beyond the schema.

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

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

The description names the resource (companion MCP servers) and the three dimensions it reports on: which serve the project's gates, which are installed on the machine, and which are wired into an agent's config. It also distinguishes itself from the mutating sibling ddflow_companions_add by framing this as a read-only inventory.

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 clear context for when the tool is relevant: checking companion coverage for gates, understanding the consequences of having no companions, and diagnosing the exit-2 condition. It does not explicitly name alternatives or exclusions, but the read-only inventory purpose is distinct enough that no sibling tool covers the same role.

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 disclosure burden. It does so by revealing the merge-not-overwrite behavior, the exit 3 refusal for non-installed servers, and the reason (a launch command that fails mid-task). This is meaningful behavioral information beyond what the schema alone shows.

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-load the action and merge semantics, and the second justifies the hard-failure behavior without repetition. No filler words or restatements of the tool name.

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

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

For a two-optional-parameter tool with no output schema, the description covers the essential invocation context: target state (already installed), behavior on conflict (merge), and failure mode (exit 3). It does not describe the success return or configuration side effects, but those are minor against the clear usage boundary.

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%, with both id and agents already described inline. The description adds no parameter-level detail beyond the schema, so the baseline of 3 applies.

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

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

The description names a specific action ('Register companion MCP servers'), qualifies the target ('ALREADY installed'), and states the merge behavior that distinguishes it from overwrite-style configuration tools. This is enough to separate it from the ddflow_companions family and other config-related siblings.

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

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

The opening clause sets the appropriate condition: this tool is for servers already present in the agent's MCP config. It also gives an explicit when-not signal by stating it refuses (exit 3) to register non-installed servers, with the failure rationale. It does not name an alternative tool, but the inclusion/exclusion boundary is clear.

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

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

With no annotations, the description carries the behavioral burden and does a good job: it discloses the exit code 3 and the three refusal conditions. The force parameter description adds that overridden conditions are recorded in the event log 'visible forever.' It doesn't describe success return values or side effects, but the core behavioral contract is clear.

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, no filler. The action is front-loaded, refusal conditions are compactly listed, and the model instruction is a single imperative. Every sentence 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 tool with no annotations and no output schema, the description covers the essential preconditions and the one required call-time parameter. It doesn't state what happens on success, but the schema's force description fills in the override behavior. The main gap is success semantics, which is minor for a completion action.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds a usage hint for the model parameter ('Pass your own model'), but this is more of a call-time instruction than new semantic meaning. The schema already documents id, sha, force, and model adequately.

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 clear verb and resource: 'Finish an item.' It then defines what finishing means by listing refusal conditions (exit 3 for unmet gates, open tasks, or reviewer model-family mismatch), which makes the tool's role concrete. It doesn't explicitly contrast with siblings like ddflow_release or ddflow_abandon, but the action is distinct enough to avoid confusion.

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 main description gives a direct usage instruction: 'Pass your own model as 'model'.' It also implies when not to call by listing refusal conditions. The force parameter's schema description adds strong routing guidance, explicitly preferring ddflow_gate_skip over force and explaining that overrides are permanently visible in the event log.

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 provided, the description carries the full burden of behavioral disclosure. It discloses that `toml` APPENDS (mutates the file), that `set` edits in place, and that appending fails on duplicate tables. It also explains the read behavior (prints knobs, values, sources, descriptions). It does not mention permissions, reversibility, or exact output formatting, but the core mutating and failure behaviors are transparent.

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 moderately sized, including a practical example that aids understanding. It front-loads the core purpose ('Read or write...') and then details the two main modes. The example adds clarity but could be trimmed slightly; nevertheless, every sentence contributes to usage understanding.

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 config tool with 4 optional parameters and no output schema, the description covers the primary use cases: reading all knobs, appending TOML, and editing via `set`. It explains failure on duplicate tables and shows a realistic usage pattern. It does not describe the exact format of the printed knobs or exit codes, but the information provided is sufficient for an agent to call the tool 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?

The schema description coverage is 100%, so the baseline is 3. The description adds value by explaining the `toml` parameter with a full example and the append behavior, and by clarifying that `set` edits in place. The `filter` parameter is not elaborated in the description, but the schema already describes it. Overall, the description enhances the schema's meaning for the key 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?

The description clearly states 'Read or write .ddflow/config.toml', specifying the resource and action. It distinguishes itself from siblings by being the configuration tool for the project, with no sibling performing similar read/write config operations. The verb is explicit and the scope is unambiguous.

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

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

It provides clear usage context: with no arguments it prints all knobs, and with `toml` it appends. It gives a concrete example of the typical use case (setting the test command) and notes that this is how a project is configured without a shell. However, it does not explicitly state when NOT to use this tool or compare it to alternatives like ddflow_setup, leaving the exclusion criteria implicit.

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

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

There are no annotations, so the description carries the burden of behavioral disclosure. It does reveal useful behavior: decisions are persisted, survive, and can be surfaced automatically to future agents via globs. However, it does not disclose side effects, authorization needs, or what happens on invocation beyond recording.

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 tight and front-loaded. Every sentence earns its place: the first defines the tool's purpose, the second paragraph gives prioritized operational guidance for the two most decision-critical 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?

With 12 parameters, no annotations, and no output schema, the description wisely focuses on the non-obvious usage context and the two easy-to-miss parameters. The schema already describes all parameters in detail, so the tool is callable correctly after reading both. It could still mention interaction with the decision_supersede/list siblings, but that is not essential for a record operation.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds real value beyond the schema by singling out `globs` and `alternatives`, explaining why they matter and instructing the agent to always set them. This helps the agent choose parameters strategically, not just fill required fields.

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 starts with a specific verb and resource: 'Record an architectural decision'. It further scopes the tool with concrete examples of what counts (data representation, boundary, library choice, invariant), making it clearly distinct from the decision_list, decision_show, and decision_supersede siblings.

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

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

The description gives an explicit trigger: 'Use when you or the operator settle a question about HOW the software is built'. It does not name alternative tools or state when not to use this one, so it falls just 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?

No annotations are present, so the description carries the burden of behavioral disclosure. It reveals that the tool returns project-wide decisions and acts as the delivery mechanism for decisions to implementers. However, it does not state whether the operation is read-only, describe the response shape, or mention any ordering or filtering 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?

Three short sentences deliver purpose, usage, and an important return-scope detail without filler. The usage directive is front-loaded and the wording is efficient, though the opening sentence could be more verb-driven.

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

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

For a one-parameter lookup with no output schema, the description covers what the tool returns and when to invoke it. It is slightly thin on output format and explicit side-effect disclosure, but adequate for a simple decision-retrieval 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 description coverage is 100%, so the single id parameter is already documented. The description only connects id to 'a specific item' without adding format, source, or interpretation details beyond the schema.

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

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

The description clearly states it returns architectural decisions governing a specific item's declared files, and adds that it also returns project-wide decisions. It is distinct enough from sibling decision tools like ddflow_decision_list or ddflow_decision_show, though it does not explicitly name an alternative.

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 'CALL THIS BEFORE IMPLEMENTING' is an explicit, strong usage trigger, and 'it is how a decision reaches the person writing the code' explains its role. It provides clear context but does not mention when not to use it or point to alternative 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?

No annotations are provided, so the description carries the full burden. It discloses a key behavioral trait: superseded decisions are kept (never deleted) and hidden unless requested, which is valuable for the agent to understand persistence and retrieval semantics. It does not cover permissions or return format, but for a simple read/list operation, this is substantial transparency.

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 with no redundancy. The core purpose is front-loaded, and the rationale for keeping superseded decisions is a meaningful addition that explains the 'all' parameter's existence. 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 tool with a single optional boolean, the description is complete enough. It states what is returned (decisions in force), the default filtering, and the rationale for the option. It does not describe the output structure, but no output schema is present, and for a list tool, the agent likely knows the decision entities from related tools. The description is adequate without oversharing.

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 schema covers 100% of parameters; the single 'all' parameter already has a clear description ('Include superseded decisions'). The description adds a bit of rationale ('how the architecture got here is what a rebuild needs') but no new semantic meaning about the parameter's format or effect beyond what the schema states. 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?

The description clearly states the tool's function: listing architectural decisions that are in force, with the option to include superseded ones. It uses a specific verb ('list' implied) and resource ('architectural decisions'), and distinguishes itself from siblings like ddflow_decision_show by focusing on the full set rather than a single decision. The behavior of hiding superseded decisions by default is explicit.

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 implicitly communicates when to use the tool: to see currently enforced decisions, and optionally include superseded ones via the 'all' parameter. However, it does not explicitly compare itself to alternatives (e.g., ddflow_decision_show) or state conditions for choosing this tool over others. It provides context about the default behavior but lacks explicit exclusions or alternative 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, the description carries the full burden. The verb 'Read' clearly signals a non-mutating operation, and the description discloses what the tool returns in terms of content. It does not explicitly state side-effect absence, but for a read tool the semantics are sufficiently transparent.

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 with no filler. The core purpose and content are front-loaded, and the sibling comparison is placed exactly where it adds value. 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 single-parameter read tool with no output schema, the description fully covers what the agent needs: what the tool does, what content it returns, and when to use it relative to its sibling. Nothing essential 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% and the single parameter 'id' is documented as 'Decision id.' The description does not add additional parameter-level meaning, but it does not need to because the schema already fully covers the parameter. 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?

The description states a specific verb ('Read') and a specific resource ('ONE architectural decision in full'), and enumerates the content: context, decision, consequences, and rejected alternatives. It also distinguishes itself from ddflow_decision_list, making the tool's role unmistakable.

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 explicitly contrasts with ddflow_decision_list ('gives you the titles') and tells the agent when to use this tool: before working against a decision and especially before proposing something it already considered. This is clear, actionable 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 provided, the description carries the full burden of behavioral disclosure. It clearly states that decisions are never edited or deleted, so this operation does not modify or destroy the original decision—it only marks a replacement relationship. This adds meaningful context beyond the schema, though it does not cover reversibility or error cases.

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

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

The description is two sentences with no wasted words. The primary action is front-loaded in the first sentence, and the second sentence provides essential domain context. Every word 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 simple tool with fully described parameters and no output schema, the description sufficiently explains what the tool does and the underlying immutability principle. It could mention what happens after success, but given the low complexity and clear schema, it is adequately complete.

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

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

Schema coverage is 100%, with each parameter already defined ('id' as the decision being replaced, 'by' as the replacement, 'reason' as why it changed). The description does not add extra parameter-level detail beyond the overall purpose, so the baseline score of 3 is appropriate.

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

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

The description uses a specific verb ('Mark'), a clear resource ('a decision'), and specifies the action ('replaced by a newer one'). It also explains the domain model (decisions are never edited or deleted), which differentiates this tool from editing/deleting and from sibling tools like decision_add or decision_list.

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

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

The description implies when to use the tool (marking a decision as replaced) and hints at the prerequisite that a newer decision must exist ('a reversal is a new decision that names the old one'), but it does not explicitly name alternatives or conditions for not using it. This is adequate but relies on inference.

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

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

With no annotations, the description must stand alone, but it never states whether this tool only inspects and reports, or may also repair/correct issues such as stale indexes or orphaned worktrees. It also does not disclose output format, side effects, or failure behavior, which is significant for a 'doctor' 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?

The description is one compact, front-loaded sentence that uses a colon-delimited list to pack five concrete check categories. Every item earns its place and no filler is present.

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?

Although the tool has no parameters, there is no output schema and no annotation safety profile, so the description should at least indicate whether the tool mutates state and what it returns/reports. It does neither, leaving an agent unable to predict the outcome of invoking ddflow_doctor.

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 input schema has zero parameters, so there is nothing for the description to explain; the baseline is 4. The description still adds value by listing the focus areas of the check.

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 the tool performs an integrity/health check and enumerates specific conditions it examines: log corruption, dependency cycles, unknown dependencies, orphaned worktrees, stale index. This makes the scope clear, though it is phrased as a noun phrase rather than an explicit verb command and does not contrast with ddflow_status.

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

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

No guidance is given about when to run this tool versus related tools such as ddflow_status, ddflow_recover, or ddflow_cleanup. The intended use is only implied by the 'health check' label; there are no conditions, prerequisites, or exclusions 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?

No annotations are provided, so the description carries the full disclosure burden for this mutation tool, and it does substantial work. It surfaces a non-obvious failure mode (recording 'passed' when a reviewer couldn't run), explains that command+exit_code turn an assertion into verifiable evidence, mentions the digest being recorded against output_file, and notes the family-independence model requirement. This is meaningful behavior an agent could not infer from the 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?

Three sentences, all load-bearing, with the core action and the critical warning front-loaded before supporting detail. The 'IMPORTANT' caveat is prominent where it matters most. Slightly dense, but every clause earns its place with no filler.

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

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

For a 9-param mutation tool with no annotations and no output schema, the description covers the key behavioral traps (unavailable-vs-passed, evidence requirements, digest verification) that an agent must know to avoid silently losing data. It does not describe the return value or confirm whether an id/gate must pre-exist, but it is otherwise sufficient for correct invocation.

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 a baseline of 3 applies. The description goes beyond the schema by explaining the semantic relationship between command and exit_code ('what make an outcome evidence rather than an assertion'), the rejection of gates without them (evidence_required), the requirement that reason accompany failed/unavailable/partial/skipped, and the trust-model purpose of output_file ('a digest is recorded... rather than taken on trust'). It adds genuine interpretability over raw field docs.

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 ('Record the outcome of a gate you performed') and enumerates the exact allowed values (passed/failed/unavailable/partial/skipped). The instruction distinguishes it from sibling gate tools like ddflow_gate_run and ddflow_gate_skip by emphasizing this is the post-hoc recording action, so an agent can tell them apart.

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 strong contextual guidance on when to choose 'unavailable' vs 'passed' and explicitly flags the destructive consequence of misrecording (an entire review silently vanishing). It also instructs passing the reviewer's model for family independence. However, it never names alternative tools (e.g. ddflow_gate_skip, ddflow_gate_status) or states when NOT to use this tool, leaving some routing implicit.

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

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

With no annotations, the description carries the full burden of behavioral disclosure. It does reveal that the tool executes commands and records results, which implies side effects. However, it does not mention failure behavior, permissions, or what 'evidence' means, so some behavioral context is missing for a command-execution tool.

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

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

Two sentences, no wasted words, and the core action is front-loaded. The second sentence directly addresses the most likely confusion with a sibling tool, making the description both compact and informative.

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 simple two-parameter tool, the description covers the essential invocation details and differentiates from the relevant sibling. The absence of an output schema means return behavior is not explicitly described, but the tool's purpose and parameters are sufficiently clear for correct use.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds meaningful parameter context by explaining that the gate is a command gate (tests, linters) and that agent gates are not valid here, which goes beyond the schema's simple 'Gate id' description.

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

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

The description states a specific action ('Execute a command gate') and resource ('tests, linters'), and clarifies the result is recorded with evidence. It also distinguishes itself from ddflow_gate_record by excluding agent gates, making the tool's scope clear relative to a key 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 description explicitly says when not to use this tool: agent gates cannot be run this way and should instead use ddflow_gate_record. This provides clear routing guidance and names the alternative, leaving no ambiguity about the intended use case.

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 behavioral burden. It discloses that skipping requires a reason, that the reason is permanently recorded in the event log, and that required gates still block. It could add whether the operation is reversible or what response shape to expect, but the key side effects are transparent.

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 sentences, with no filler. The core action and mandatory reason are front-loaded in the first sentence, and the rest supplies decision-relevant constraints. Every sentence 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?

Given three simple required parameters and no output schema, the description covers what the tool does, when to use it, what side effects to expect, and which gates cannot be skipped. An agent has enough to select and invoke it correctly.

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

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

Schema description coverage is 100%, so the schema already documents id, gate, and reason. The description reinforces that reason is mandatory and auditable, but does not add substantial new semantic detail beyond the schema. The baseline of 3 applies because the schema does the heavy lifting.

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

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

The description opens with a specific verb and resource: 'Skip a gate ON THE RECORD, with a mandatory reason.' It then distinguishes this tool from the broader act of forcing past everything, making clear it drops a single named step. The phrase 'auditable escape hatch' further differentiates it from gate-related siblings.

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

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

The description explicitly says this is 'the one to reach for' when a gate is blocking completion, and contrasts it with forcing past everything at once. It also sets a clear exclusion: gates listed in `gates.required` still block and are not optional, so an agent knows when NOT to use 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?

With no annotations, the description carries the burden of behavioral disclosure. It does add an important interpretation rule: gates marked '?' did not run and are a coverage gap, never a pass. However, it does not explicitly state that this is a read-only operation, mention prerequisites, or describe error/edge-case behavior, leaving some ambiguity.

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

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

The description is two short sentences with no redundancy. The core purpose is front-loaded, and the '?' clarification earns its place by preventing a dangerous misinterpretation.

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

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

For a low-complexity tool with one parameter and no output schema, the description adequately explains the returned information and includes a key edge-case caveat. It could mention what happens when no gates remain or an item is not found, but those are minor 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 100%, so the schema already fully documents the single 'id' parameter. The description does not add additional meaning to the 'id' parameter beyond what is already present, so the baseline score of 3 is appropriate.

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

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

The description clearly identifies the resource (an item's quality pipeline) and the output: current position, next gate, and gate instruction. It uses 'Where an item stands' rather than an explicit verb, and does not explicitly distinguish itself from siblings like ddflow_status or ddflow_next, so it falls 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?

Usage is implied: call this tool to see an item's current gate status and what gate comes next. However, there is no explicit statement about when to prefer this over sibling tools such as ddflow_status, ddflow_progress, or ddflow_next, and no alternatives 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?

With no annotations, the description carries full responsibility for behavioral disclosure. It clearly states that it mutates the file, runs the gate, expects a non-zero exit (indicating the gate caught the mutation), and restores the file. It also explains the failure semantics: a mutation with absent or ambiguous 'old' text is a failure, and Exit 1 from the tool indicates the gate did not catch the mutation. This is thorough and unambiguous.

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 divided into three paragraphs. The first is concise and action-focused. The second explains the rationale behind the tool, which is useful context but could be shortened. The third clarifies a failure condition. Overall, every sentence adds value, but the middle paragraph is slightly verbose. The structure front-loads the core action and then elaborates, which is effective.

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 tool with two parameters, no output schema, and no annotations, the description covers the key behaviors: mutation application, exit-code expectations, file restoration, and failure conditions. It does not explicitly state what the tool returns on success (presumably 0) or how multiple mutations are handled sequentially, but these are inferable from the description. The absence of an output schema reduces the need to explain return values, so the description is sufficiently complete.

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

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

The input schema already provides descriptions for both parameters (id and gate), achieving 100% coverage. The description does not add any additional parameter-specific guidance, such as examples or further constraints beyond 'Must be a command gate.' Since the schema handles parameter documentation, the description's lack of extra detail keeps this at the baseline 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?

The description opens with a concrete, action-oriented statement: 'Break what a gate guards and require it to NOTICE.' It then specifies the exact procedure (apply mutations, run, require non-zero exit, restore file). This clearly distinguishes it from sibling tools like ddflow_gate_run (which presumably runs gates normally) and ddflow_gate_record (which registers mutations).

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 establishes clear context: it is the 'anti-vacuous-pass check turned on the checks themselves.' This implies it should be used when verifying that a gate actually catches its registered mutations. While it doesn't explicitly name alternative tools or state when not to use it, the purpose and scenario are evident from the wording and sibling names. It stops short of explicit exclusions or direct comparisons.

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 provided, the description carries the full burden of behavioral disclosure. It explains the core effect (renewing a lease) and the consequence of non-action (expiry and takeover), which is valuable. However, it does not disclose failure modes, idempotency, prerequisites, or what the response looks like, leaving some behavioral ambiguity.

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 with no wasted words. The action is front-loaded, and the usage guidance follows naturally. Every sentence 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 single-parameter tool with no output schema and no annotations, the description provides the essential what, when, and why. It omits potential edge cases like 'what if the lease already expired?', but given the tool's simplicity, the description is sufficient for the core calling scenario.

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 schema already covers the only parameter fully with 'Item id', so the baseline is 3. The description adds minimal semantic value by linking 'the item' to the id, but does not provide additional details such as format, scope, or required state of the item.

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 clearly states a specific operation ('Renew the lease on an item'), which is unambiguous and distinct from generic verbs. It does not explicitly compare itself to sibling lease-related tools such as ddflow_claim or ddflow_release, but the action and resource are clear enough for an agent to understand what it does.

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 explicit usage guidance: 'Call periodically during long work'. It also explains the negative consequence of not calling (lease expiry and potential takeover by another agent), which helps the agent decide when to invoke it. It does not mention alternatives or exclusions, but the context is clear.

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

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

Even though no annotations are provided, the description discloses that the tool is 'Read-only' and warns that returned pages may be project-specific overrides rather than defaults. This is useful behavioral context that prevents the caller from assuming the output is always the canonical template.

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 front-loaded with its purpose, then moves clearly through when to call it, what each argument form returns, and the read-only project-override caveat. Every sentence earns its place; the contrast with sibling descriptions is relevant, not 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 help/metadata tool with one optional parameter and no output schema, the description provides everything needed to invoke it correctly: purpose, first-use trigger, argument behavior, allowed topics, side-effect safety, and variability of the response. There are no major 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 input schema already documents the optional topic parameter and its allowed values, and the description repeats that list without adding deeper per-topic semantics. Schema description coverage is 100%, so the description contributes little beyond what the schema already 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 clearly states that ddflow_help is the overview tool: 'What ddflow IS, what it can do, and what the workflow is.' It also distinguishes itself from the one-tool-at-a-time sibling descriptions by explicitly saying those assume you already know which tool to pick. The intended role, scope, and argument modes are all immediately clear.

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 an explicit trigger: 'Call this first if you have not used it before.' It also explains why the sibling descriptions are not substitutes and tells the caller exactly when to omit the topic versus provide one. This is strong when-to-use 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, the description carries the full behavioral burden. It discloses that results are ordered chronologically and adds a valuable operational detail: exit 2 means nothing matched and should be treated as an answer, not a failure. It does not explicitly state permissions or read-only behavior, but that risk is low for a history view.

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 dense paragraphs with no wasted repetition. The first front-loads the core purpose and selection context; the second delivers filter semantics and the non-obvious exit-code meaning. Every sentence contributes to correct selection or invocation.

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 history-listing tool with no output schema, the description covers purpose, ordering, filtering, and a non-obvious exit-code behavior. It does not specify the exact return shape, but 'ONE timeline' plus the event-family list is enough for an agent to invoke and interpret it. The main gap is not naming specific sibling alternatives.

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 input schema already covers all four parameters, so the baseline is 3. The description adds conceptual meaning: `item` means one task's whole life, `kind` groups event families, and `since` defines a time window. It does not add much about `limit`, but the schema already documents that.

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 clearly defines a single timeline of events in chronological order and enumerates the event families it covers. It contrasts itself with 'the other views' that answer current state, which helps an agent distinguish it from status-like siblings, though it never names a specific alternative 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?

It gives explicit context for when to use the tool: when something looks wrong and the question is 'how did it get like this.' It also explains filter usage and exit code 2 as a valid no-match result. However, it does not name specific sibling tools or state when not to use it, 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 provided, the description must carry the full burden of behavioral disclosure. It explains the hook's behavior (refuses commits on uncovered paths) and clarifies the nuance between installation status and actual enforcement. However, it doesn't describe side effects of install/uninstall (e.g., whether they modify files, require permissions, or are reversible), which would be valuable given no annotations.

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 concise, with two sentences that pack essential information. It front-loads the core purpose (inspect/install the hook), explains its uniqueness, and clarifies the critical status nuance. No wasted words; every sentence 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 simple tool with one parameter and no output schema, the description is quite complete. It covers the tool's purpose, the key behavioral nuance (status vs enforcement), and the action options. The only minor gap is the lack of detail on what install/uninstall do in terms of side effects or prerequisites, but given the tool's simplicity, this is a minor omission.

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

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

The schema description is 100% covered (the action parameter is fully described with its options). The description adds value by explaining what 'status' reports (installation AND policy effectiveness) and implying install/uninstall actions, going beyond the bare schema. Since schema coverage is high, a baseline of 3 applies, but the description adds meaningful context about the action's semantics, justifying a 4.

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 clearly states the tool's purpose: inspect or install an enforcement git hook that blocks commits touching paths not covered by a live lease. It uses specific verbs ('inspect', 'install') and a specific resource ('enforcement git hook'), and it distinguishes itself from siblings by emphasizing it's the one layer not depending on agent agreement—a unique function among the sibling tools.

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 when to use it: 'status' reports installation and whether the policy blocks, which is useful context. It implicitly suggests using install when a block policy exists but no hook is installed. However, it doesn't explicitly name alternatives or when-not to use it, though the description's focus on the enforcement layer makes the usage context clear.

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

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

With no annotations, the description carries the full burden. It discloses the non-destructive default ('writes NOTHING until `apply` is true'), the guess-based nature of the proposal, and the exit code meaning (Exit 2 = nothing found). This is thorough behavioral disclosure for a tool that reads and proposes.

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 longer than average but every sentence adds value: purpose, usage timing, rationale, guess caveat, and exit code. It is front-loaded with the core purpose and default behavior. Slightly verbose 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 tool with no output schema and no annotations, the description covers the essential context: what it does, when to use, what it doesn't do, and how to interpret failure. It does not describe the return format or the structure of the proposal, but that is minor given the other details. Overall, adequately complete for an agent to invoke it correctly.

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

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

Schema coverage is 100%, so the baseline is 3. The description adds context about `apply` (default false, reports only) and mentions the guess nature, but does not significantly enhance the parameter meanings beyond what the schema already provides. It does not explain `max_tasks` or `include_done` beyond schema descriptions.

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 clearly states a specific action: read existing history artifacts (todo checklists, lessons, ADRs, unmerged branches) and propose them as queue items. It also clarifies the default behavior (reports only, no writes until `apply` is true), which distinguishes it from write-oriented tools. The purpose is unambiguous and distinct from siblings like ddflow_import_verify.

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

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

Explicitly states when to use: 'Call this right after `ddflow_setup` on any repository that is not brand new.' It explains why (empty queue hides in-flight work) and points to an alternative (`import-existing-project` prompt) for fixing the guessed structure. This gives clear decision guidance without ambiguity.

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?

There are no annotations, so the description carries the full behavioral burden. It fully discloses the read-only nature ('Read-only; writes nothing'), the meaning of exit codes, what each of the three answer groups covers, and its relationship to other checks. This is exemplary for a no-annotation 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?

The description is long but every sentence carries substantive information: the core question, the three answer categories, exit code semantics, and the boundary with ddflow_doctor. It is front-loaded with the essential purpose and read-only guarantee, then expands in a tightly structured way.

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?

Despite having no output schema and no annotations, the description tells an agent everything needed to call the tool and interpret results: what it verifies, what exit codes mean, when to run it, and what it deliberately excludes. The absence of an output schema is compensated by the detailed behavioral explanation.

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 has zero parameters and the schema is already complete with an empty object definition, so there is no parameter meaning left to add. This matches the baseline for a no-parameter tool.

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, multi-part question—'Was this project's history imported, is that import still true, and did anyone FINISH it?'—and then names the exact resources and checks involved. It is clearly distinct from siblings like ddflow_import and ddflow_doctor.

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

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

Explicitly states when to call it ('after any import, and whenever you are about to hand out imported work'), explains exit code meanings, and directly differentiates it from ddflow_doctor by saying what it does not cover and that ddflow_doctor should still be run. This is unambiguous usage 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?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It conveys persistence and deduplication intent ('never re-learned') and a transferability quality bar, but it does not describe write semantics such as append-only behavior, idempotency, what gets replaced, or what response to expect.

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

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

Three short sentences, front-loaded with the core action and immediately followed by concrete triggers and a quality bar. Every sentence earns its place and 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?

The when-to-use guidance is strong and the schema fully documents all 8 parameters. However, with no annotations and no output schema, the description omits any sense of what the call returns, how the recorded lesson is later retrieved, or how it interacts with sibling tools like ddflow_lesson_search and the reconstruction workflow.

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

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

Schema description coverage is 100%, so the baseline of 3 applies even though the description adds no parameter-level syntax or relationships. The 'transferable rule' guidance hints at how to fill fields like rule/why/how, but it does not map to specific 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 the action ('Record a lesson'), the resource (a lesson in the corpus), and the intended outcome ('never re-learned'). The verb distinguishes it from sibling read/search tools like ddflow_lesson_search, and the 'lesson' resource separates it from task_add, phase_add, decision_add, and research_add.

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 explicit trigger conditions: 'Use after any bug, any operator correction, any surprise.' It also gives a quality requirement for the content ('Make the rule transferable'). It does not explicitly list exclusions or compare against alternatives, so it falls just short of full when-to-use/when-not-to-use 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?

No annotations are provided, so the description carries the burden of behavioral disclosure. It reveals the BM25 relevance algorithm, which is useful, but it does not explicitly state that the tool is read-only or has no side effects. For a search tool this is likely implied, but the absence of any annotation or side-effect disclosure leaves some ambiguity.

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 only two sentences, with the first sentence stating the core purpose and the second giving usage guidance. Both sentences earn their place, and critical information is front-loaded.

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 simple two-parameter search tool, the description is adequate: it explains what it does and when to use it. However, since there is no output schema and no annotations, the description could mention what the returned data looks like or that it is informational-only, but given the tool's simplicity, this is a minor gap.

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

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

Schema description coverage is 100%, with both parameters already documented in the input schema. The description itself adds no new parameter-level detail beyond what the schema provides, so the baseline of 3 applies.

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

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

The description clearly states the tool searches past lessons by relevance using BM25, which is a specific verb (search), resource (past lessons), and method (BM25). This distinguishes it from sibling tools like ddflow_history or ddflow_recall, which likely have different scopes.

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 explicitly instructs to use the tool 'before starting work' and 'whenever something surprises you,' providing clear timing and context for invocation. It does not mention when not to use it or name alternatives, but the guidance is actionable and sufficient for this tool.

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