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

No annotations exist, so the description carries the burden; it does state that the tool is non-mutating ('audit reports violations and never fixes them') and what it inspects, which is the key behavioral trait. It leaves unstated whether the check reads from local refs or contacts origin, and how long/heavy it is, so it falls short of fully self-describing for an annotation-free 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?

Three sentences, front-loaded with the action and checks, then usage, then the boundary and the non-fixing guarantee. Every sentence adds distinct information; nothing is restated from the schema or title.

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 purpose, trigger, exclusion, and the read-only nature of the audit. With no output schema, the description gives only a coarse notion of the result ('pass/fail gate', 'reports violations') without saying whether findings come back as a list, counts, or per-commit detail — a modest gap for a diagnostic 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 there is a single optional parameter whose default and origin fallback are already documented in the schema. The description adds no additional semantics about baseBranch (e.g., what 'origin fallback' means in practice, or effect on which commits are considered), 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?

Specific verb (audit) plus a concrete resource (branch commits against the LogNexus review gate), then enumerates the five checks performed: commit format, Authored-by trailer, Git Notes coverage, subtask file contracts, author/reviewer separation. It also explicitly distinguishes itself from lognexus_timeline, so an agent can pick correctly without opening a schema.

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

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

Gives an explicit trigger ('before merging or before opening a pull request') and an explicit exclusion with the alternative named ('Not for producing the PR narrative (use lognexus_timeline)'). Both when-to-use and when-not-to-use are stated, not inferred.

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

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

With no annotations, the description carries the burden and does disclose key behavior: atomicity, that the engine refuses to run on a protected branch, and that it rejects files outside the contract. It stops short of stating the success response shape (e.g. commit SHA) or what happens to state if finishing fails midway.

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 operation and dense but purposeful — no filler. It is on the longer side and packs several concepts (contract validation, gate, finishing) into clause form, which slightly taxes scanning but nothing is wasted.

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

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

For a 7-parameter mutation tool with no output schema and no annotations, the description covers the essential operating constraints (protected branch, file contract, atomicity). It could be more complete about the return value and interaction between finishTask and commit failure, but no critical calling information 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 description coverage is 100%, so every parameter including enum and trailer identities is already documented in the schema. The description adds essentially no parameter-level detail beyond what structured fields provide, 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?

States specific verb and resource ('Atomically create a Git commit') and enumerates the bundled operations (conventional format, trailers, contract validation, task finishing, note attachment). It explicitly differentiates from the sibling lognexus_note_attach, so an agent can select it without opening 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?

Gives an explicit when ('creating any commit on a LogNexus branch, including the atomic subtask commits that close a Tn') and two explicit when-nots with the alternative named (retro-attaching a note → lognexus_note_attach; bypassing the gate → refused). Routing is unambiguous.

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

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

With no annotations, the description carries the burden and does well: it discloses that this is a mutation writing into a specific notes ref, that the commit must already exist, and that re-attaching is a repair path. It stops short of saying whether an existing note is overwritten or what the tool returns on success/failure, which matters for a write operation on a ref another tool also writes.

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

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

Front-loaded with the action and target ref, then the usage condition, then the exclusion. Slightly redundant: the exclusion is stated twice ('Not for normal commits' and 'attaching again is only needed when the note was lost'), but the second pass adds the repair rationale rather than pure repetition.

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 tool with no annotations and no output schema, the description supplies target, default, ref namespace, and the routing decision against lognexus_commit. The remaining gap is overwrite semantics when a note already exists at that ref, which an agent calling a 'repair' tool would want to know.

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 is fully documented there. The description only restates the HEAD default and the 'already exists' precondition, adding no syntax or format detail beyond the schema, 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?

States a specific verb and resource: attach the current LogNexus state as a Git Note at refs/notes/lognexus onto an existing commit, defaulting to HEAD. It explicitly names the sibling lognexus_commit and explains how this differs from it, so an agent can distinguish the two without opening either schema.

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

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

Gives explicit when-to-use (backfilling commits created outside the commit engine, repairing a lost note) and explicit when-not-to-use (normal commits, because lognexus_commit attaches the note atomically). The alternative and the condition selecting it are both 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 must carry behavioral burden; it does disclose the read-only nature, the note ref, and the HEAD default. However, it does not say what happens when a commit has no LogNexus note (error vs. empty result), which is the main failure mode an agent would encounter.

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 tight sentences: what it does, how to use it, and what it is not for. The core purpose is front-loaded and nothing is wasted.

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

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

For a one-parameter read tool with no output schema, it is largely complete, indicating the payload is parsed JSON with tier/subtask/contract fields. The absence of a missing-note behavior description keeps it from full completeness.

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, including its HEAD default. The description only repeats the HEAD defaulting, adding 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?

States a specific verb (read) and resource (LogNexus Git Note at refs/notes/lognexus) and describes the return as a parsed JSON payload. It is clearly distinguishable from the sibling lognexus_note_attach, which handles creation.

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 names the triggering context ('verifying that a commit carries the expected tier, subtask and contract before a review or a merge') and an exclusion with a redirect ('Not for creating or repairing notes (use lognexus_note_attach)'). Both when-to-use and when-not-to-use are covered.

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

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

With no annotations, the description carries the full burden and does disclose the key trait: clearing is destructive and drops the whole contract, which warns the agent against casual use. It stops short of stating reversibility, whether any confirmation is required, or what the empty state means for subsequent calls, leaving some behavioral gaps.

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

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

Four short sentences, each earning its place: purpose first, then CLI equivalence, then use cases, then the negative case and destructiveness warning. Front-loaded and free of 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 parameterless, annotation-free, output-schema-free tool, the description supplies everything needed to call it safely: what it does, when to use it, when not to, and the destructive consequence. Nothing an agent requires for correct invocation 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?

The tool takes zero parameters, so per the baseline the schema fully covers the calling contract and the description has nothing to compensate for. There is no parameter content the description could add value to.

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 ('Reset') and resource ('persistent LogNexus agent state to empty'), and explicitly maps itself to the CLI equivalent. It also names the sibling it is not (lognexus_state_finish_task), so an agent can distinguish it from the other state tools without opening 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?

Gives concrete triggering conditions — abandoning an issue, switching to an unrelated task, recovering from a corrupted state file — and an explicit exclusion with the correct alternative ('Not for finishing a single subtask (use lognexus_state_finish_task)'). No inference is required to choose between this and its siblings.

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

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

With no annotations, the description carries the burden and does disclose the mutation, its precondition, and that an updated state is returned, plus the atomic alternative. It stops short of stating idempotency, what happens if taskId does not exist, or whether completion 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?

Three sentences, each load-bearing: purpose and return, CLI equivalent, then when-to-use and when-not-to-use. Front-loaded with the action and 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 one-parameter state mutation with no output schema, the definition covers purpose, precondition, and alternatives well. The one gap is that 'return the updated state' does not describe the shape of that state, which the agent cannot infer without an 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 coverage is 100% and the single taskId parameter is documented with an example ('T1'), so the description adds nothing beyond it. Baseline 3 is appropriate when the schema fully documents the only parameter.

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 completed in persistent state and return the updated state. It also names the CLI equivalent and explicitly distinguishes itself from lognexus_commit and lognexus_state_set_task, so an agent can separate it from siblings without reading schemas.

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

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

Gives an explicit precondition ('when the subtask work has already been committed and its Git Note attached') and two named exclusions with the correct alternatives: lognexus_commit with finishTask:true for atomic finishing, lognexus_state_set_task for contract edits.

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

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

With no annotations, the description carries the burden, and it does disclose meaningful behavior: this is a disk read of a named file, it returns a snapshot bounded by the last sync, and it will not validate against Git/GitHub. It does not say what happens when state.json is absent or unreadable, nor any permission or error behavior, leaving a small gap.

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

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

Three sentences, front-loaded with what is returned, then usage condition, then exclusions with named alternatives. Nothing is redundant and each sentence carries a distinct routing or content signal.

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 usefully enumerates the returned state fields, and with no parameters there is little schema detail to miss. The only shortfall is undefined behavior for a missing or malformed state file, which matters for a single-tool read of a local artifact.

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 correctly implies a no-argument call and spends its words on return contents instead. There is no parameter syntax an agent could get wrong.

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 ("Return") and resource ("persistent LogNexus agent state (.lognexus/state.json) as stored on disk"), then enumerates the contents: active issue, current subtask and file contract, completed subtasks, and last sync timestamp. It also explicitly distinguishes itself from lognexus_state_sync and the set/finish-task siblings, so an agent can route without opening 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?

Gives a positive trigger ("Use when you need the current contract or completion list and nothing has changed the branch since the last sync") plus two explicit negative cases, each paired with the correct alternative tool. That is the full when/when-not/alternatives pattern.

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 does the heavy lifting: it discloses that the contract is 'closed' and persisted, and that the file scope is enforced downstream by the commit engine and the audit — non-obvious behavior an agent needs. It does not say whether re-calling overwrites an existing contract or is idempotent, which is a remaining gap for a state-mutating tool.

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

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

Three tightly packed sentences: what it does, the CLI equivalent, then when/when-not. Front-loaded and free of filler.

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

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

For a 7-parameter mutation tool with no annotations and no output schema, the description covers purpose, persistence, enforcement, and routing to siblings. The only omission is what the call returns or how conflicts with an already-set contract are handled.

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, but the description adds conceptual value by grouping allowedFiles/forbiddenFiles/decisionBudget/verificationCmd under a single 'closed delegation contract' and explaining that the tier is the 'active issue tier' — semantics the per-param schema text alone doesn't convey.

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

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

States a specific verb+resource: marking a subtask in progress and persisting its delegation contract (files, budget, verification command) plus issue tier. It maps cleanly to the sibling set and explicitly distinguishes itself from lognexus_state_finish_task and lognexus_state_get.

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 the trigger condition ('when you begin a new subtask and need the file scope enforced') and names both exclusions with their correct alternatives — lognexus_state_finish_task for completion and lognexus_state_get for reading the contract. Nothing is left to inference.

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

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

No annotations are supplied, so the description carries the full burden, and it does disclose key traits: it mutates the store, rewrites .lognexus/state.json, and shells out to git and gh (implying local repo and GitHub auth/network requirements). It stops short of stating failure behavior, idempotency, or what happens to existing local state on conflict.

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, each earning its place: purpose/side effects first, then use cases, then the exclusion with the alternative. The mutating nature is front-loaded before the routing guidance.

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-param tool with no output schema, the description covers the mutation target, external dependencies, and that the updated state is returned. The remaining gap is error/conflict handling, which matters for a tool that rewrites a state file but is not strictly required 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?

The tool takes zero parameters, so there is nothing for the description to clarify beyond the empty schema; baseline 4 applies. The description correctly implies no arguments 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?

Names a specific verb (reconcile/sync) and resource (persistent state), plus the concrete artifacts involved: the Git branch, GitHub metadata, and .lognexus/state.json. It explicitly distinguishes itself from the read-only sibling lognexus_state_get, so an agent can pick correctly without opening either schema.

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

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

Gives explicit triggers (after checkout, rebase, opening a PR, suspected staleness) and an explicit exclusion with a named alternative: 'Not for a plain read of what is already on disk (use lognexus_state_get)'. Both when-to-use and when-not-to-use are covered.

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; it discloses a read-only, low-cost snapshot, and it clarifies that refreshing state is delegated to another tool. It does not state anything about output shape or auth, but read-only + cheap + scoped is meaningful behavioral context; without annotations this is strong but not exhaustive.

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

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

The description consists of three sentences: what it inspects, when to use it, and when not to use it. The 'what' is front-loaded, and the routing sentence earns its place by preventing misuse of sibling tools.

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-argument status tool, this is nearly complete: it enumerates the data points returned and points elsewhere for anything richer. It stops short of describing the shape or fields of the response (for example, whether the tier is a string, and how 'not a repo' is represented), and there is no output schema to cover that 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?

The tool takes zero parameters, so under the rubric it scores at the baseline of 4. There is no parameter content to describe, and the description correctly focuses on what the tool returns instead of inventing argument 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?

The definition opens with a specific verb ('Inspect') and then enumerates exactly what is inspected: Git branch, Git-repository status, active issue, routing mode, and recommended model tier. A sibling such as lognexus_state_get or lognexus_state_sync is clearly distinguishable from this tool by that enumeration, so it meets the 5 criteria.

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 definition states the trigger for use, 'a cheap read-only snapshot before choosing a branch, a tier, or a next action,' and it names two alternatives for solving adjacent problems: lognexus_state_get for the subtask contract and lognexus_state_sync for refreshing state from Git and GitHub. Both the exclusions and the alternative tools are explicit.

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

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

With no annotations, the description carries the full burden and does well: it discloses zero network calls, zero-PII payloads, the exact storage location (.lognexus/telemetry.json), and that data never leaves the working directory. It implies 'clear' removes the metrics store but does not state whether that is irreversible or what happens to concurrent sessions, which keeps it short of a 5.

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

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

The action inventory is front-loaded and the usage/privacy constraints follow in two tight sentences with no filler. The initial sentence is long but every clause maps to a distinct action or guarantee.

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

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

For a six-action mutation tool with no annotations and no output schema, the description supplies privacy posture, storage path, and purpose. The remaining gaps — what each action returns and whether 'clear' is recoverable — are modest but real given the destructive 'clear' option.

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 would be 3; the description earns above that by giving each enum action operational meaning — 'enable strictly local performance metrics', 'inspect the zero-PII local payload', 'clear the metrics store' — beyond the raw enum labels. outputPath semantics are left entirely to the schema, which already documents the default.

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

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

The description names a specific resource (local telemetry) and enumerates every operation — status, enable, disable, inspect, report, clear — in verb+object form. It also distinguishes itself from siblings implicitly by scoping to performance/ROI metrics stored locally, rather than state, audit, or Git operations. An agent can tell what this tool does without opening the schema.

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

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

It gives clear trigger conditions ('Use when measuring subtask duration, Git Notes coverage and estimated cost savings') and an explicit exclusion ('Not for any form of upload'). The gap is that no sibling tool is named as an alternative, so routing between lognexus_status, lognexus_audit, and this tool is left to inference.

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

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

With no annotations, the description carries the burden and does real work: it names the data sources (Git Notes, subtask IDs, tiers, Authored-by/Reviewed-by trailers) and the three output renderings, which imply a read-only synthesis operation. It stops short of stating repository/auth prerequisites, failure behavior for an unknown base branch, or whether it mutates any 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 purpose and output surface are front-loaded in the first sentence, followed by one usage sentence and one exclusion sentence; every sentence earns its place. The opening sentence is dense and slightly overloaded with the enrichment list, which is up to 20 words of detail before the agent knows the output formats.

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, and the description compensates by describing the three output forms and the enriched fields. For a zero-required-parameter read tool this is close to complete; only the environment/prerequisite context (needing a git repo with the base branch present) is left implicit.

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

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

Schema coverage is 100%, so the baseline is 3. The description's mention of 'Markdown table, JSON or a PR body draft' loosely maps to the format enum and 'against a base branch' mirrors baseBranch, but it adds no format-specific behavior (e.g., what the PR body draft contains versus the table) 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 resource ('branch Journey Timeline against a base branch') and enumerates what the output contains (commits enriched with Git Notes, subtask IDs, tiers, trailers) and its renderings. It explicitly distinguishes itself from lognexus_audit, so an agent can separate the two without inspecting 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?

Gives concrete trigger conditions ('preparing a pull request description', 'reviewing the subtask sequence of a branch') and an explicit exclusion with the correct alternative ('Not for judging compliance (use lognexus_audit, which reports violations rather than a narrative)'). Both when-to-use and when-not-to-use are present.

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