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 the concrete checks (commit format, Authored-by trailer, Git Note presence, subtask file contracts, reviewer/author separation), which is real behavioral value, but it never states that the operation is read-only/non-destructive, what the result looks like, or how failures are reported.

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

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

A single front-loaded sentence with no filler; each listed item corresponds to a real check. Slightly dense but appropriately sized for the tool's scope.

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

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

With no output schema and no annotations, the description should say more about what the audit returns (pass/fail per check? report text?) and whether it mutates anything. The enumeration of checks helps, but return-shape and side-effect expectations remain unspecified.

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?

Only one parameter, baseBranch, and schema coverage is 100%, with the default ('main' with origin fallback) already documented in the schema. The description adds nothing about how the branch is used in the comparison, so baseline 3 applies.

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

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

Specific verb ('Audit') plus resource ('branch commits against the LogNexus review gate') and an explicit enumeration of the five checks performed. An agent knows exactly what the tool inspects, though nothing distinguishes it from siblings like lognexus_status or lognexus_commit.

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 statement of when to run this audit, whether it is a pre-commit gate check or a post-hoc review, or how it relates to the many sibling tools (lognexus_commit, lognexus_status). Usage must be inferred entirely from the name and checklist.

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, so the description carries full burden. It helpfully discloses the side effects (contract validation, automatic task finishing, Git Note attachment) and the atomic framing, but omits failure/rollback semantics, permissions/auth needs, and how 'automatic task finishing' interacts with the finishTask boolean — a notable gap for a mutation tool.

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

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

A single front-loaded sentence with no wasted preamble; every clause names a real behavior. It is dense but not padded.

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

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

Covers the creation behavior well, but with no output schema and no annotations the description should say what the tool returns (e.g., commit SHA) and what happens when contract validation fails. For an atomic commit tool, those are material omissions.

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 documents all five parameters with examples. The description adds context about trailers and validation but no parameter-specific detail beyond that; baseline 3 is appropriate when 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?

States a specific verb+resource ('create a Git commit') and enumerates the bundled effects (trailers, validation, task finishing, note attachment). The 'single operation' framing implicitly differentiates it from the granular siblings like lognexus_note_attach and lognexus_state_finish_task, though it never names them outright.

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: the phrase 'in a single operation' hints this replaces chaining note_attach + state_finish_task, but there is no explicit when-to-use, when-not-to-use, or prerequisite guidance. An agent must infer the routing decision from the bundled-effect 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?

No annotations exist, so the description carries the burden. It helpfully discloses the target ref namespace and the HEAD default, but omits whether an existing note is overwritten, whether git repo state is required, and what the call returns — meaningful gaps for a write operation.

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

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

Two tight sentences, front-loaded with the action and the ref, followed by the default. Nothing is wasted and nothing critical is buried.

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, no-annotation, no-output-schema tool, the description covers the core identity but leaves out overwrite semantics, permission/repo requirements, and note content — details an agent needs before invoking a mutating tool.

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

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

Schema coverage is 100% and the single commitRef parameter is fully documented in the schema, so the schema does the heavy lifting. The description only restates the HEAD default, adding no format examples or edge-case meaning.

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 ('Attach') and resource ('LogNexus state as a Git Note') plus the exact ref (refs/notes/lognexus). It implicitly distinguishes itself from the read-side sibling lognexus_note_show, though it never names it.

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

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

Usage is only implied: the agent can infer this writes a note to a commit, but nothing says when to prefer it over lognexus_commit, lognexus_note_show, or lognexus_state_sync, nor any prerequisites like being in a git repository.

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 the non-obvious storage location (refs/notes/lognexus) and that the return value is a parsed JSON payload, which clearly frames this as a read. It does not say what happens when no note exists on the commit, whether the ref can be overridden, or what the payload's shape is.

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 zero waste, front-loading the action and the exact ref being read before the default behavior. Nothing redundant or padded.

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

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

For a read tool with no output schema and no annotations, the description should say more about what the parsed payload contains or how a missing note is surfaced. The ref location and default are covered, but the return contract remains opaque.

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% for the single commitRef parameter, so the schema already documents accepted forms (SHA, branch, tag, HEAD) and the default. The description's 'Defaults to HEAD' merely restates the schema; no additional semantics are contributed.

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 ('Read'), a precisely named resource (the LogNexus Git Note under refs/notes/lognexus), and the result ('parsed JSON payload'). The read-only nature distinguishes it implicitly from the write-side sibling lognexus_note_attach, though it never names that 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?

'Defaults to HEAD' gives a usable calling convention, but the description never explains when to reach for this tool rather than a sibling like lognexus_note_attach, lognexus_state_get, or lognexus_timeline. Usage is implied by the verb 'Read' rather than spelled out.

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

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

No annotations are provided, so the description carries the full burden. It does disclose the core behavioral effect: the persistent agent state is reset to empty. However, it omits whether the reset is irreversible, what else is affected, and whether any confirmation or permissions are required.

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 front-loaded sentence with no wasted words. It states the action, target, and resulting state efficiently.

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

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

For a zero-parameter state-clearing tool without annotations or an output schema, the description covers the basic operation. It is still incomplete because it does not explain destructive implications, when to choose it over state_sync or state_get, or any side 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 tool takes zero parameters, so the baseline is 4. The empty schema is fully described, and the description adds no param semantics because none are needed.

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

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

The description states a specific verb and resource: reset the persistent LogNexus agent state. It also adds the outcome ('to empty'), which distinguishes it from sibling tools such as state_get, state_sync, and state_set_task, though it does not explicitly name those alternatives.

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 no guidance on when to use this tool versus siblings, when not to use it, or what prerequisites or safeguards apply. It merely states the operation.

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 correctly signals a mutation and helpfully discloses that the updated state is returned (relevant since there is no output schema). However, it says nothing about idempotency, error behavior for invalid or already-completed task IDs, or whether the parent task's state is affected.

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 action front-loaded and the return behavior second. The CLI-equivalent parenthetical is compact and aids routing rather than padding.

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

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

For a single-parameter mutation it covers the essentials: what changes and what comes back. Missing are failure modes, idempotency, and any note on the parent task or state file, which matter more because no annotations exist to cover them.

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 taskId parameter is documented with an example format ('T1'). The description's '<id>' reference matches the schema but adds no new semantics; baseline 3 is appropriate.

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

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

States a specific verb and resource ('Mark a subtask as completed') plus the side effect of returning updated state, so the agent knows exactly what it does. It does not explicitly differentiate itself from siblings like lognexus_state_set_task or lognexus_state_clear, which is the only gap.

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 action implies when to use it (a subtask reaches completion), but there is no explicit when/when-not guidance and no mention of the alternatives in the sibling list. An agent must infer that set_task is for modifying fields and clear is for removal.

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 does disclose what the tool exposes (active issue, current subtask, completed subtasks, last sync timestamp) and where that comes from, but says nothing about behavior when .lognexus/state.json does not yet exist (empty object, error, or defaults) or whether the read has side effects.

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

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

A single front-loaded sentence that names the resource, its backing file, and the returned fields with zero filler.

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

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

No output schema exists, so the description must describe the return value, and it enumerates the persisted fields adequately. The only material omission is the empty/missing-state behavior for a tool that is likely called before state is initialized.

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?

Zero parameters, so the baseline is 4. The description correctly implies no inputs are needed to fetch the full state.

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

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

Specific verb+resource: returns the persistent agent state, naming the backing file (.lognexus/state.json) and the exact fields returned. It is clearly the read counterpart to state_set_task/state_sync/state_clear, though it does not name those siblings explicitly.

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

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

Usage is implied by the getter naming and the enumeration of persisted fields, but there is no explicit statement of when to call it versus lognexus_status or the state mutation siblings, and no prerequisites or exclusions are given.

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 does disclose that this is a mutation and that it returns the updated state, plus the CLI equivalent, but it never says what happens to a previously active subtask, whether the title overwrites an existing one, or what error conditions look like.

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

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

A single sentence that leads with the action and packs the CLI equivalence into a parenthetical. Nothing is wasted and nothing important is buried.

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

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

For a two-parameter state mutation with no annotations and no output schema, the description is minimally adequate: it says what changes and that state is returned. It omits the side effects on the prior active subtask and any indication of failure behavior, which an agent would need before calling it in a 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%, with taskId and title both documented in the schema (including title's optionality), so the baseline is 3. The description adds only the CLI signature hint '[id] [title]', which restates rather than extends schema semantics.

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

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

States a specific verb and resource: mark a subtask as in progress, returning updated state. That distinguishes it implicitly from lognexus_state_finish_task and lognexus_state_get, but no sibling is named explicitly, so it falls short of a 5.

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

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

The 'in progress' framing implies this is the tool to call when starting or resuming work on a subtask, but there is no explicit when-to-use or when-not guidance, and no pointer to finish_task/state_get for the adjacent operations.

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 does disclose that the result is the updated state, but nothing about whether existing local state is overwritten, what happens on conflict with the remote, whether this mutates the working tree or commits anything, or what GitHub auth/network access is required. For a sync operation with write potential, these are material omissions.

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

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

One sentence, front-loaded with the action and source of truth, ending with the return behavior. No filler. It could be marginally better structured by splitting the call-to-action from the return semantics, but nothing is wasted.

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

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

With no annotations and no output schema, the description is the only source of behavioral information, and it omits side effects, conflict/merge behavior, idempotency, and required environment (Git repo, GitHub credentials). Given a state-mutating sync in a family of state tools, this leaves an agent unable to predict the outcome confidently.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate and the baseline is 4. The description does not need to elaborate on inputs beyond this.

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 (synchronize) and a specific resource (persistent state), plus the sources (current Git branch and GitHub metadata) and that it returns the updated state. An agent can distinguish it from lognexus_state_get or lognexus_state_clear. It stops short of naming a sibling or explicit scope boundary, so not a 5.

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

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

There is no guidance on when this should be called instead of lognexus_state_get, lognexus_commit, or lognexus_status, and no prerequisites are stated. The only implied context is that a Git branch must be current, which the agent has to infer from the phrase 'current Git branch'.

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 exist, so the description carries the full burden. It implicitly conveys a read-only inspection and enumerates the returned fields, which is genuinely useful, but never explicitly states 'no side effects', whether it touches the filesystem/network, or what the response shape looks like. Adequate but short of what an unannotated tool warrants.

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

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

One sentence, front-loaded with the verb and no filler. The list is long but each item is a distinct returned datum, so little is wasted.

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

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

With no output schema, the description must convey return content, and it does so by naming five concrete fields. Missing only the explicit read-only guarantee and any note on failure when the directory is not a Git repository.

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

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

The tool takes zero parameters, so the baseline is 4. The description instead spends its words itemizing the inspection targets, which is the useful analog for a no-arg 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?

Starts with a specific verb ('Inspect') and enumerates exactly which fields are surfaced: Git branch, repo detection, active issue, routing mode, model tier. This is far more concrete than a name restatement. It does not, however, contrast itself with the similarly named sibling lognexus_state_get, so an agent has no signal on how they differ.

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

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

There is no statement of when to call this versus lognexus_state_get, lognexus_state_sync, or lognexus_timeline, which all read adjacent state. Usage must be inferred entirely from the field list.

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

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

With no annotations, the description carries the full burden, and it does add real context: 'zero-PII payload', 'anonymous community' vs 'local' telemetry. However, it never states that 'clear' irreversibly destroys the metrics store, that 'report' writes a file to disk, or that 'enable' with share=true requires acceptTerms — all material behaviors for a tool that includes a destructive action.

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

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

A single sentence that front-loads the most-used mode ('Inspect telemetry status') and then lists the remaining actions compactly with zero filler. The 'or'-chained enumeration is slightly list-like but every clause maps to a real enum value.

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 six-action dispatcher with no annotations and no output schema, the description covers all action names but leaves gaps: nothing about what status/inspect/report actually return, nothing about the terminal/irreversible nature of 'clear', and no prerequisites for the anonymous-sharing path. Adequate to call correctly, but not 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 each of the four parameters is already documented in the input schema, including the share/acceptTerms coupling and the outputPath default. The description adds no parameter-level meaning beyond that, so the baseline 3 applies.

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

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

The description enumerates all six actions with concrete verbs and objects ('inspect telemetry status', 'generate telemetry markdown reports', 'clear metrics store'), so the tool's scope is unambiguous. It never names or contrasts with a sibling tool, but 'telemetry' is a distinctive domain no sibling covers, making overlap unlikely.

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 action list implies what each mode does, but there is no when-to-use / when-not-to-use guidance, no explicstatement of ordering or prerequisites, and no hint about which action an agent should pick by default (the schema, not the description, says it defaults to 'status'). Usage is inferable but not directed.

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; 'Reconstruct' implies a read-only aggregation, and the enumeration of enrichment data and output formats is genuinely informative. However, it doesn't state prerequisites (git repo state, whether notes must already exist), whether it touches the remote, or what happens when no notes/trailers exist — gaps that matter for a composite read 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?

A single dense sentence that front-loads the core action and then the data sources and output formats. It is efficient for the amount of information conveyed, though packing four enrichment sources into a clause makes it slightly hard to scan.

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 read tool with no output schema and no annotations, the description covers purpose and formatting options adequately. It leaves unclear what the JSON/table payload contains structurally and what preconditions or failure modes exist, which a richer description should have supplied.

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 both parameters are already documented, and the description only restates the format choices and base-branch comparison. It adds minor semantic value by clarifying that 'pr-body' yields a pull-request draft, but offers no extra detail on branch resolution or format behavior 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?

States a specific verb ('Reconstruct') and a well-defined resource ('branch Journey Timeline against a base branch') and enumerates the enrichment sources (Git Notes, subtask IDs, tiers, trailers) plus output formats. It is clearly distinguishable from generic siblings like lognexus_audit or lognexus_note_show, though it never names those alternatives directly.

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: the 'against a base branch' framing suggests PR/release review scenarios, but there is no explicit when-to-use, when-not-to-use, or pointer to a sibling such as lognexus_audit or lognexus_note_show. An agent must infer the routing decision.

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