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

With no annotations, the description carries the full burden and mostly delivers: exclusivity, time-limitation, TTL semantics, renewal path, and the two outcome branches (acquired=true with fencing_token, or acquired=false with holder and remaining expiry). It omits permission/prerequisite requirements and whether contention should be retried.

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, front-loaded with the core action, then the parameter meaning, then the return contract. No filler or restatement 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?

An output schema exists, so return values need not be spelled out, yet the description usefully summarizes both outcome branches. Combined with the sibling naming, an agent has almost everything needed; only concurrency/retry guidance and prerequisites are absent.

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

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

Schema description coverage is 0%, so the description must compensate. It explains timeout_seconds as the lease TTL (not just a timeout) and ties renewal to it; file_path's meaning is conveyed by "a lease on a file." It does not document format constraints or edge values (e.g. minimum TTL).

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 precise verb (Acquire) and resource (exclusive, time-limited lease on a file), plus the intent behind it (before editing it). This is clearly distinguishable from siblings like memkernel_release_lease, memkernel_heartbeat_lease, and memkernel_checkout without opening any schema.

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

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

Gives the triggering context ("before editing it") and routes renewal to the sibling memkernel_heartbeat_lease. It does not explicitly state when-not to use it (e.g. read-only work) or contrast with memkernel_checkout, so it falls short of full alternative coverage.

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 add meaningful behavior: decisions are durable, never compacted away, and re-using a key supersedes the old value while retaining it as a deprecated assumption. It omits permissions, idempotency, and whether ordering matters, but the supersede/retention semantics are genuinely non-obvious value.

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

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

Three short sentences, front-loaded with the core action, and the example earns its space by disambiguating key/value syntax. 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?

An output schema exists, so return values need no explanation, and the durability/supersede model is covered. The remaining gap is the undocumented rationale parameter and no explicit sibling routing, but otherwise the agent has enough to call 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 0% and the description compensates only partially: the example clarifies decision_key (dotted namespace, e.g. 'auth.method') and decision_value format. The required 'rationale' parameter is never explained, so one of three required inputs remains undocumented anywhere.

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 ('Record') and resource ('canonical architectural decision') scoped to 'the active branch'. It is clear what the tool does, though it never explicitly contrasts itself with close siblings like memkernel_note or memkernel_log_execution.

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

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

Usage is implied rather than stated: durable, never-compacted decisions suggest this is for canonical architecture choices rather than transient notes. There is no explicit 'use this instead of X when Y' routing, so the agent must infer the boundary with memkernel_note.

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 implies a session-scoped state mutation but does not say what happens on failure, whether uncommitted work is preserved or discarded, whether a lease is required, or whether the switch 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?

A single short sentence with the operation front-loaded and the precondition set off in parentheses. Efficient, though the brevity edges into under-specification.

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?

An output schema exists, so return values need not be explained, and the one-parameter surface is simple. Still, for a state-mutating session tool that interacts with fork/rollback/lease siblings, the description omits error behavior and session-scoping details an agent would want.

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

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

Schema description coverage is 0%, so the schema contributes only a name and type. The description adds one useful constraint (branch must already exist), but says nothing about format, source, or how to obtain a valid branch_id.

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

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

States a specific verb ('Switch') and resource ('this session's active branch'), which clearly separates it from read-oriented siblings like memkernel_list_branches or memkernel_diff_branches. It does not explicitly name a sibling to contrast against, but the effect of the call 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?

Only guidance is the parenthetical precondition 'it must exist'. There is no statement of when to use checkout rather than memkernel_fork_investigation or memkernel_rollback, nor how to discover a valid branch_id (e.g., via memkernel_list_branches).

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

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

With no annotations, the description carries the full burden, and it does disclose meaningful behavior: it computes a merge base and surfaces conflicts between sides, which tells the agent this is a non-mutating analytical operation. However, it says nothing about permissions, cost, or whether it writes anything (e.g., a diff artifact), leaving gaps 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?

A single front-loaded sentence that states the action first and then the outputs, with no filler. Well sized for the operation.

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?

Because an output schema exists, the description need not explain return values, and it already previews the key result categories. For a two-parameter read tool that is close to adequate, but the missing parameter meaning and total absence of usage/behavioral context (no annotations to lean on) leave it only minimally 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 0%, so the description must compensate for the two undocumented parameters, and it largely does not. 'Two branches' plus 'each side' only loosely implies branch_a and branch_b are the compared endpoints; nothing clarifies whether these are names, IDs, or references.

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

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

The description gives a specific verb+resource ('Compare two branches') and even enumerates the comparison surface: merge base, events ahead on each side, conflicting decisions and facts. That is far more informative than the name alone and implicitly separates it from list_branches/history. It stops short of naming a sibling to differentiate against, so a 4 rather than 5.

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

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

There is no when-to-use guidance, no prerequisites, and no reference to alternatives such as history or query_state. The comparison intent is implied by the verb, but an agent gets no help deciding when a diff is warranted versus another inspection 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 full burden, and it does disclose genuine behavioral traits: the holder/token/expiry check shares the append's transaction (atomicity), and it explicitly scopes the guarantee ('protects the memory event; it does not write or lock the file'). It omits failure behavior and auth requirements, but the atomicity and scope disclosure is substantive.

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 its precondition in the first sentence, then a compact explanation of the mechanism. It is short and wastes little, though the second sentence's phrasing ('it does not write or lock the file') is terse enough to be slightly cryptic.

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

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

An output schema exists, so return values need not be explained, and the fencing/atomicity semantics are covered. But for a lease-fenced, transaction-scoped mutation with five undocumented parameters, the description leaves failure modes, parameter meanings, and the relationship to the lease lifecycle unaddressed.

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

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

Schema coverage is 0% with five required parameters, so the description must compensate and it largely does not. Only 'token' loosely maps to fencing_token via the 'holder, token and expiry check' phrase; file_path, decision_key, decision_value, and rationale are left entirely to their bare schema titles.

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 ('Record a decision') with an explicit precondition ('only while this agent holds the current lease'), which conceptually separates it from the sibling memkernel_append_decision. However, it never names the unfenced sibling or states the contrast explicitly, so the differentiation is inferential rather than stated.

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 precondition 'only while this agent holds the current lease' tells the agent when this tool is applicable, which is meaningful usage context. But it gives no guidance on the alternative (memkernel_append_decision) or what to do when no lease is held, leaving the routing decision to inference.

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

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

With no annotations, the description carries the full burden. It does disclose one important side effect – the session is switched to the new branch – and hints at disposability. It does not say whether the fork is reversible, how the branch is later discarded or merged, or whether the parent branch 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?

Two tight sentences with the core action front-loaded and the usage cue following. No filler or restatement 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?

An output schema exists, so return values need not be explained, and the branch/session semantics are covered. Still missing are the fork-branch naming guidance and any lifecycle context (how to inspect, merge, or discard the fork) needed to use this 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 single parameter fork_branch_name has 0% schema description coverage and the description never mentions it, so no naming constraints, format, or collision behavior are conveyed. Only one parameter keeps this from being worse.

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

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

The description gives a specific verb ('Fork') and resource ('the active branch at its head'), plus the resulting state change of switching this session to the new branch. However, it never distinguishes itself from closely related siblings like memkernel_checkout or memkernel_rollback, so an agent must infer the difference.

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

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

'Use for speculative work you may want to discard' supplies a genuine use-case cue, which is better than nothing. But it names no alternatives and no when-not condition, leaving the agent to guess why it would fork rather than check out an existing 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 are provided, so the description carries the full disclosure burden. It usefully discloses the boolean failure semantic and the required agent reaction, which is real behavioral value beyond the schema. However, it omits prerequisites (is this call idempotent? does it require auth?), the recommended heartbeat interval, and whether extension can fail for reasons other than lease loss.

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 zero filler, front-loading the action and then the failure contract. Every clause earns its place and the guidance is actionable.

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?

An output schema exists, so the description is not obligated to explain return values, and the boolean meaning it does give is a bonus. Still, with no annotations and 0% parameter coverage, the definition leaves an agent guessing about heartbeat cadence and about what file_path/fencing_token must contain.

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

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

Schema description coverage is 0% and there are two required parameters, so the description must compensate and does not. Neither 'file_path' nor the non-obvious 'fencing_token' concept is mentioned; the phrase 'a lease you hold' never explains that identity is conveyed via these two fields. This is the weakest dimension for the definition.

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: 'Extend a lease you hold by its original TTL.' An agent can distinguish this from memkernel_acquire_lease and memkernel_release_lease by the 'extend an already-held lease' framing. It stops short of explicitly naming the siblings it is not.

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?

Implies the usage context ('a lease you hold') and gives a clear failure-path instruction: on False, 'stop editing and re-acquire,' which implicitly routes to memkernel_acquire_lease. It does not state when to heartbeat (cadence relative to TTL) or when not to call it, so guidance remains inferred rather than explicit.

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

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

With no annotations, the description carries the full burden, and it does disclose two real behaviors: results are limited to the active branch, and only "live" (non-dead) events are returned, plus most-recent ordering. It omits any statement about the limit parameter's effect, ordering guarantees, or pagination behavior, which is a notable gap for a zero-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?

A single front-loaded sentence with zero waste; the scope constraint comes first and the parenthetical adds operational value rather than filler.

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

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

An output schema exists, so return values need not be explained, and the branch/recency scoping is covered. Still missing is any definition of "live events" versus the events written by memkernel_log_execution/memkernel_note, and any explanation of the limit parameter, leaving the agent to guess at result size and content boundaries.

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

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

Schema description coverage is 0% and the single parameter ("limit", default 30) is never mentioned in the description, so the agent gets no explanation of what it bounds, its valid range, or what happens when it is exhausted. The schema's type and default are the only source of 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 ("List"), a specific resource ("live events"), and a scope ("most recent", "on the active branch"), so the agent can distinguish it from memkernel_rollback or memkernel_log_execution. It falls short of a 5 only because "live events" is internal jargon whose definition is never pinned down.

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

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

The parenthetical "(ids for rollback)" implies this is the discovery step preceding memkernel_rollback, which is genuine usage signal. However, there is no explicit when-to-use/when-not framing and no guidance on how it relates to siblings like memkernel_log_execution, memkernel_note, or memkernel_query_state.

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

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

With no annotations at all, the description carries the full behavioral burden and falls well short. It does not say whether recording a task overwrites a prior directive, whether the call is idempotent, whether it requires an active branch to already exist, or what happens on the active branch when the task is later rolled back.

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 the action verb first and zero wasted words. It is efficient, though arguably too terse for a tool whose structured fields carry no descriptive text.

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?

An output schema exists, so return values need not be explained, but for a state-mutating memory-kernel tool with 0% parameter coverage and no annotations the description is under-specified. It omits the branch prerequisites and the interaction with rollback, checkout, and log_execution that a calling agent needs to sequence calls 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 0%, so the description must compensate, and it partially does by naming both concepts: the "directive" and "constraints." It adds no format or semantic detail, however — for example whether directive is free-form prose and what kinds of items belong in the constraints array.

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 ("Record") with a specific resource ("task directive and constraints") and scopes it to "the active branch," which is more precise than a bare name restatement. It does not, however, distinguish itself from closely related siblings like memkernel_note or memkernel_append_decision, so an agent must infer the difference from the name alone.

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

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

There is no when-to-use guidance and no stated prerequisites, e.g. whether a branch must be checked out first via memkernel_checkout or whether this is a one-time per-task call. No alternatives (memkernel_note, memkernel_append_decision) are referenced, so the invocation context must be guessed.

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, but this is a zero-parameter listing tool, so the safety profile is largely self-evident. It does disclose one behavioral fact beyond the name — that the output includes the current session's active branch — but says nothing about read-only guarantees, auth, or ordering.

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

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

A single front-loaded sentence with zero filler. It states the resource and the notable output detail in the fewest words possible.

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?

An output schema exists, so return-shape explanation is unnecessary, and there are no parameters to document. The description is adequate for this tool's complexity, though the absence of any hint about ordering or how branches are identified is a small residual 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 and the schema has no properties, so there is nothing for the description to disambiguate. Baseline 4 applies for a parameterless 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?

States a specific verb+resource ('List all branches') and adds the useful scope detail that the session's active branch is included. It does not, however, differentiate itself from adjacent siblings like memkernel_diff_branches or memkernel_history, which an agent might reasonably weigh against 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?

There is no when-to-use or when-not-to-use guidance, and no mention of alternatives. The description simply declares what it returns; an agent gets no routing signal for choosing this over diff_branches or history.

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 a heavy burden and delivers real behavioral detail: a non-zero exit_code opens a blocker that a later zero exit clears, and facts are tracked with changed values deprecated as assumptions. It does not state whether an active task/checkout/lease context is required, which is a notable gap given the leasing siblings.

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, no filler, with the core action front-loaded and the consequential blocker/facts behavior following immediately. 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?

An output schema exists, so return values need no explanation, and the mutating behavior (blocker open/clear, assumption deprecation) is well covered. What remains missing is prerequisite context — whether this requires an init'd task or an acquired lease — and any mention of the 'output' parameter.

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

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

Schema coverage is 0%, so the description must compensate, and it substantially does: it explains the exit_code semantics, tells you what belongs in facts (verified environment facts, e.g. python version) and how changing facts are treated. Only the 'output' parameter is left entirely undefined.

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: 'Log a tool/terminal execution'. A reader immediately knows what the tool does. It does not explicitly distinguish itself from the many sibling memory tools (memkernel_note, memkernel_append_decision), which is why it falls short of a 5.

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

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

Usage context is implied (call after running a command) and the exit_code contract hints at when a blocker matters, but there is no explicit when-to-use/when-not guidance or routing to alternatives such as memkernel_note for unverified observations. Implied usage only.

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 the full burden. It usefully discloses that notes are subject to garbage collection over time, which is a key behavioral trait beyond the schema. However, it omits return behavior, note size limits, whether notes are queryable, and interaction with memkernel_trigger_gc.

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?

Single front-loaded sentence with zero waste. Every word (Record, ephemeral, scratchpad, GC) adds meaning.

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?

An output schema exists, so return values need not be explained. For a one-parameter tool, the description covers the essential lifecycle trait (ephemeral, GC'd) that the schema cannot express. Minor gaps around size limits or queryability are acceptable given the tool's simplicity.

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

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

Schema description coverage is 0%, so the description must compensate. It clarifies the note is an ephemeral scratchpad, distinguishing the content from durable logs or decisions. The single required string parameter's semantics are adequately implied by the verb 'Record' plus the scratchpad context.

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: write an ephemeral scratchpad note. Clearly distinguishable from siblings like memkernel_append_decision or memkernel_log_execution by its ephemeral/scratchpad nature. Lacks explicit sibling differentiation but the purpose is unambiguous.

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

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

No guidance on when to use this versus memkernel_append_decision (durable decisions) or memkernel_log_execution. The 'ephemeral' hint implies transient use cases but doesn't state exclusions or alternatives.

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

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

With no annotations, the description carries the full burden, and it does disclose a meaningful behavioral trait: ephemeral tool-execution logs and scratchpad notes are excluded by default and only surfaced on opt-in. 'Return' strongly implies a read-only, non-mutating operation. It still omits permissions, cost, and whether the snapshot is consistent, keeping 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?

Two sentences, front-loaded with what is returned and followed by the one opt-in behavior. The enumeration is dense but every listed category earns its place by telling the agent what the payload contains.

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-required, read-only query with an output schema, the description is nearly sufficient: it signals the payload shape and the ephemeral flag's effect. It would be complete with brief routing guidance against sibling tools and a note on branch_id.

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

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

Schema description coverage is 0%, so the description must compensate for two parameters. It explains include_ephemeral well ('raw tool-execution logs and scratchpad notes not yet compacted'), but says nothing about branch_id beyond the schema's default of 'main'. Partial compensation warrants a 3.

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 ('Return') and resource ('consolidated memory of a branch'), then enumerates the categories returned (tasks, decisions, workspace facts, blockers, leases, events), which is unusually concrete. It does not, however, differentiate itself from siblings such as memkernel_history or memkernel_diff_branches, so an agent must still infer which read tool fits.

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 second sentence gives a clear conditional for one parameter ('Set include_ephemeral=true to also see...'), which is genuine usage guidance. But there is no statement of when to reach for this tool versus the many sibling read/query tools, so usage is only implied.

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

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

No annotations are provided, so the description carries the full disclosure burden. It does usefully disclose that the call can fail with 'false' when the token is stale or belongs to another holder, which is real behavioral detail, but it says nothing about permissions, whether a repeat call is harmless, or how non-stale errors surface.

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, no filler, and the core action is front-loaded ahead of the failure caveat. Every clause carries information.

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

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

For a simple two-parameter lease operation with an output schema to cover the return shape, the description covers purpose and the main failure mode adequately. It is thin only on permissions and idempotency, which are not strictly needed 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 description coverage is 0%, so the description must compensate. It partially does by explaining that the fencing_token can go stale when the lease is re-granted, which gives real meaning to that parameter, but file_path is never described and no format or expected-value guidance is offered.

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 ('Release a lease you hold') that is unambiguous and naturally separates it from the acquire_lease and heartbeat_lease siblings. It stops short of naming an alternative explicitly, so it is clear but not maximally differentiating.

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 'you hold' implies the precondition (you must currently own the lease) and the second sentence sketches the failure context, but there is no explicit when-to-use / when-not guidance or named alternative for edge cases. Usage 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 full burden and does well: it discloses that later events are reverted but preserved in the audit log, and that recovery is possible by forking. It omits prerequisites such as lease/confirmation requirements and whether the rollback is atomic or interrupts in-flight work.

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

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

Three short sentences, front-loaded with the action and target, followed by consequence and recovery. No filler or restatement 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?

An output schema exists so return values need not be explained, and the description covers the mutation's effect and recovery path for a one-parameter destructive operation. Remaining gaps are prerequisites (permissions/lease state) that would fully close the loop for a mutation tool with no annotations.

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

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

Schema description coverage is 0% and the single integer parameter is undocumented in the schema, so the description must compensate. It identifies what target_event_id means and directs the agent to memkernel_history to obtain valid values, which is meaningful guidance beyond the bare property name.

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 (roll back) plus the exact resource and scope (the active branch's live timeline) and the anchor (target_event_id). This cleanly distinguishes it from siblings like memkernel_checkout, memkernel_fork_investigation, and memkernel_history.

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 operational guidance: obtain event ids via memkernel_history and explains the recovery route (fork from retained events). It does not state explicit when-not conditions (e.g., whether an active lease or an alternative branch operation is preferred instead), so it falls 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 carries the full behavioral burden. It discloses what happens (older tool logs and notes are folded into a semantic snapshot) and what is returned (token counts before/after), which is useful. But it omits whether the fold is reversible, whether detail is lost, whether a lease is required, or whether it affects other branches — material gaps for a mutating compaction 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 tight sentences with zero filler: the operation is front-loaded, the mechanism follows, and the return value is stated last. 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?

An output schema exists, so the return contract is covered and needn't be explained. But for a mutating, potentially lossy compaction operation with no annotations and an undocumented parameter, the description is only adequate — it should state reversibility, scope of impact, and lease/permission requirements.

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

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

Schema description coverage is 0% for the single 'target_branch' parameter. The description's phrase 'a branch's memory' implies the branch is selectable but never names or explains the parameter, nor mentions the 'main' default, so it only partially compensates for the coverage gap.

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

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

States a specific action (compact a branch's memory) and the mechanism (folding older tool logs and notes into a semantic snapshot), which is a distinct operation no sibling tool performs. It clarifies the jargon-heavy name 'trigger_gc'. However, it does not explicitly contrast itself with sibling tools like memkernel_rollback or memkernel_history, so it falls short of the top band.

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 word 'now' implies this is an on-demand, manual trigger as opposed to an automatic compaction, which is implicit usage context. There is no explicit statement of when to invoke this versus waiting for automatic GC, nor any prerequisites or exclusions.

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