Hexum

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

Since no annotations are provided, the description carries the full burden of behavioral disclosure. It explicitly states 'Deterministic; no LLM,' which clarifies execution behavior, and mentions that the report may include skill levels, giving insight into output variety. While it doesn't explicitly say the tool is read-only or describe error behavior, the word 'check' implies a safe inspection, and the provided details add meaningful context beyond the schema.

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

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

The description is remarkably concise, with each sentence serving a distinct purpose: the main action, the deterministic nature, the potential report content, and the conditional routing to hexum_skill. Information is front-loaded and there is no redundancy or filler.

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

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

The description covers the core purpose and a key conditional, but leaves gaps for a tool with three parameters and no output schema. It does not explain how the input modes (files vs paths vs workspace) differ, nor does it detail the report format or the meaning of skill levels (lite, full, ultra). Given the tool's complexity and lack of structured metadata, the description is only partially 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 only 33% (only workspace has a description), yet the tool description does not explain the roles of files, paths, or workspace beyond what the schema already states. The description says 'check the workspace' but does not clarify how files and paths blobs relate to reading from disk, leaving agents without sufficient guidance on parameter usage. This fails to compensate for the low schema coverage.

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

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

The description states a clear and specific action: checking the workspace against architecture.hexum and reporting layer/import drift. It also includes a conditional for skill handling, which further distinguishes it from siblings like hexum_review or hexum_expand. The purpose is unambiguous and actionable.

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 provides a specific conditional instruction to call hexum_skill when skill is on and SKILL.md is missing, which is a useful routing cue. However, it does not offer broader guidance on when to use this tool versus other checking or review tools, nor does it state exclusions or alternative scenarios beyond that one condition.

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 transparency burden. It clarifies that this is a report and enumerates the health states and outputs, strongly implying a read-only operation. It doesn't explicitly state side-effect-free behavior or any permissions, but the report nature covers most risk.

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: the first front-loads the output contract, the second gives the call trigger. No filler or redundancy.

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 report tool, the description covers what it returns and when to call it. The absence of an output schema is mostly compensated for by the explicit output summary, though it doesn't describe the full response shape.

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

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

The tool has zero parameters, so the baseline is 4. The description does not need to document parameters, and none are missing.

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 concrete 'Drift report' with a defined output set (score, health, churn, violations), making the tool's purpose clear. It does not directly contrast with sibling reports like hexum_loop_status, but the drift terminology and session scope are specific enough to orient an agent.

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?

Includes an explicit trigger: 'Call when the agent is repeating edits or failing the same check.' It does not list alternatives or exclusions, but the stated condition is actionable and sufficient for a 0-parameter report.

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

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

With no annotations provided, the description must carry the behavioral burden. It explicitly states 'Does not write the files; returns patches', which is a key non-destructive behavior. However, it does not disclose other potential effects, such as whether it modifies any internal state or what the exact format of 'patches' is. This is a partial disclosure but not comprehensive.

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

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

The description is two concise sentences, front-loaded with purpose and key behavioral detail. Every sentence adds value; there is no fluff or redundancy.

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

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

The tool has one optional parameter and no output schema. The description explains the purpose and the fact that it returns patches, but it does not elaborate on the structure of the patches or how they should be applied. Given the simplicity, it is mostly complete, but the lack of output format details is a minor gap.

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

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

The schema covers 100% of the single parameter with a clear description ('Existing architecture.hexum so already-present forbids are omitted.'). The tool description itself does not add parameter details beyond the schema, but the schema is sufficient. 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 states a specific action ('synthesize'), a clear resource ('architecture.hexum forbid lines and SKILL.md directives'), and the context (from session violations). It also clarifies that it does not write files but returns patches, which distinguishes it from other hexum tools like hexum_check or hexum_expand. The purpose is unambiguous and differentiated.

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

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

The description implies the tool should be used when there are session violations, as it says 'From this session's violations'. However, it does not explicitly state when to use it versus alternatives, nor does it mention any exclusions or prerequisites. It gives context but no direct routing to this tool over 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?

No annotations are provided, so the description carries the full behavioral burden. It usefully discloses that the tool returns full source, but it does not clarify whether 'expand' also modifies the file, whether it is purely read-only, or how failures like 'symbol not found' behave.

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, tightly written sentence with no filler. The core action, target, and output are front-loaded, making it easy for an agent to parse quickly.

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

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

For a two-parameter tool with a simple return value, the description is mostly adequate, and the schema covers the parameters. However, with no annotations and no output schema, the description should at least hint at side effects or selection context; those gaps leave some ambiguity for an agent deciding to call this 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?

The input schema already provides full coverage for both parameters: file_path is 'Relative workspace path to the file' and symbol_name is 'Exact identifier'. The description adds no additional parameter-level meaning beyond naming the kind of symbol ('function, class, or method'), so it stays at the baseline.

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

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

The description clearly states a specific verb ('Expand'), a specific resource type ('one skeletonized function, class, or method'), and the result ('return its full source'). This makes the tool's role immediately distinguishable from siblings like hexum_shrink, which likely performs the inverse operation.

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 'skeletonized' implies this tool is used after a shrink/skeletonization workflow, and the return-value phrasing indicates it is for retrieving full source. However, it does not explicitly say when to prefer this tool over alternatives, nor does it mention any exclusions or prerequisites.

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

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

With no annotations, the description carries the full behavioral burden. It usefully discloses that the operation is in-memory only and that nothing is stored, and it mentions the return value. It does not explain side effects on the loop's state, idempotency, or what happens if the loop_id is invalid.

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 three short sentences with no filler. The action is front-loaded, followed by the return behavior and the important in-memory guarantee. Every sentence adds useful 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 tool with no output schema, the description covers the core behavior and return value. It remains incomplete because the optional reason parameter is unexplained and there is no guidance about loop state or error behavior.

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 description does not explain either parameter. The purpose of loop_id is inferable from the tool name, but reason is completely undocumented, and the description adds no meaning beyond the schema's bare type and required fields.

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

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

The description states a specific verb and resource: 'Stop a running loop' and adds a concrete outcome: 'Returns the transcript summary.' This clearly separates it from sibling tools like hexum_loop_start, hexum_loop_status, and hexum_loop_tick.

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 'running loop' gives clear contextual guidance: the tool should be used only when a loop is active. However, it does not explicitly name alternatives or say when not to use it, though the intended use case is reasonably inferable.

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

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

With no annotations, the description carries the full burden. It discloses a key trait (the model still writes code; Hexum gates each turn) and the return of a loop_id. However, it doesn't disclose side effects, idempotency, or what happens if called multiple times, leaving significant 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?

Two sentences with zero waste. The action is front-loaded, and the behavioral note is concise and relevant.

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

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

For a tool with 4 parameters, no output schema, and no annotations, the description is sparse. It doesn't explain what 'goal' should contain, what 'files' are for, or what 'tick' means. The agent would have to infer from sibling tool names and the context, which is insufficient for correct invocation.

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

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

The description adds no parameter information. The required 'goal' parameter lacks a schema description, and 'files' is also undocumented; the description doesn't clarify either. With schema coverage at 75%, the description could compensate but does not.

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

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

The description clearly states the action (start an autonomous build loop) and the resource (a goal), and mentions the return values (loop_id and next instruction). It is distinct from sibling loop tools, though it doesn't explicitly say 'use this to start, not to continue.'

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

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

The description implies the tool is for starting a loop but provides no explicit when-to-use vs alternatives, no exclusions, and no prerequisites. It doesn't mention that subsequent steps should use hexum_loop_tick or that hexum_loop_abort would stop it.

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

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

With no annotations provided, the description carries the behavioral disclosure burden. It explicitly states that the tool does not advance the loop, effectively communicating a read-only side-effect profile. It does not discuss invalid loop_id behavior or failure modes, but for a status reader this is reasonably transparent.

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

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

Two sentences with no filler. The key action and purpose are front-loaded, and the important non-mutating caveat is placed immediately after. Every word earns its place.

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

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

For a simple one-parameter read tool with no output schema, the description is largely complete: it names the state fields returned and explicitly notes the lack of side effects. It could be more complete by stating the return format or behavior for missing loops, but given the low complexity, this is a solid definition.

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

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

The schema provides zero description coverage for loop_id, so the description must compensate. The name 'loop_id' plus the description's context ('loop state') makes the parameter's purpose inferable, but the description does not explain where the ID comes from, its format, or what happens on an unknown 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?

The description clearly states the action ('Read loop state') and specifies the resource and contents ('turns, gates, tokens, health'). It also distinguishes itself from mutating loop tools by noting it 'Does not advance the loop.'

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 makes it clear this is a read-only inspection tool and that it does not advance the loop, which implicitly separates it from hexum_loop_tick, hexum_loop_start, and hexum_loop_abort. It does not explicitly name alternatives, but the exclusion is clear.

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

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

With no annotations, the description carries the full behavioral transparency burden. It discloses internal side-effecting steps ('runs hexum_check, condenses logs, scores drift') and the return shape ('next instruction or terminal status'). It does not fully explain persistence or irreversibility, but for a no-annotation tool this is substantially transparent.

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

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

The description is two sentences with no filler. The purpose is front-loaded, and the second sentence efficiently itemizes inputs, internal operations, and outputs. 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?

Given six parameters, no annotations, and no output schema, the description covers the core loop-tick contract well: inputs, internal process, and return terminal states. Minor gaps remain around the exact role of notes/test_passed and whether stored logs are permanently mutated, but the description is still largely complete for an agent to invoke it correctly.

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

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

Schema description coverage is 0%, so the description must compensate for parameter meaning. It adds semantics for compile_output, test_output, and files ('updated files'), but leaves loop_id, notes, and test_passed to schema names alone. This is partial compensation rather than complete.

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?

Description opens with a specific verb and resource: 'Advance a Hexum loop one turn.' It distinguishes itself from siblings like hexum_loop_start, hexum_loop_abort, and hexum_loop_status by describing the per-turn tick behavior and possible terminal statuses.

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

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

The description gives clear operational guidance, telling the agent to pass compile_output, test_output, and updated files, and notes that it runs hexum_check internally. However, it never explicitly states when to choose this tool instead of hexum_check or hexum_loop_start, so the usage context is implied rather than precisely scoped.

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 usefully discloses that the tool is 'Deterministic' and that it produces a 'token delta,' which are meaningful behavioral traits beyond a generic review. However, 'token delta' is never explained (metering? cost report? persistence?), and the description does not state whether the tool has side effects, requires auth, or how workspace is used.

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 compact sentences with the core purpose front-loaded in the first sentence and the usage directive last. Every sentence earns its place, though the cryptic phrases 'Deterministic doctor' and 'token delta' slightly undermine clarity in an otherwise tight definition.

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 must carry more weight, and it falls short. It does state the return contract, but two of four parameters (files, workspace) are unexplained, the token-delta side effect is ambiguous, and there is no statement of read-only versus mutating behavior, leaving an agent to guess at invocation semantics.

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

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

Schema coverage is 50%: diff and config have descriptions, but files and workspace do not. The description reinforces the central relationship ('review a git unified diff against architecture.hexum') but does not clarify how diff and files interact, what workspace means, or when config is needed beyond what the schema already states.

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: 'Review a git unified diff against architecture.hexum,' and lists concrete return values (approved|changes_requested, violations, GitHub-ready markdown review). The purpose is clear and recognizable against the sibling names, though it does not explicitly name or contrast a sibling tool.

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

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

Gives an explicit preference directive: 'Prefer this over asking the model to review architecture,' which tells the agent when to choose this tool over a model-mediated general review. However, it offers no exclusions and does not distinguish when hexum_check or other siblings would be more appropriate.

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 delivers: it discloses returned data ('compressed sources plus token stats'), the default budget, incremental skip behavior via since_hash, and an ordering prerequisite. The only notable gap is that it never states whether the shrink is read-only or mutates workspace files, which is relevant for a tool named 'shrink'.

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?

Six dense sentences with no filler, ordered from purpose to return to parameter guidance to prerequisite. Every sentence earns its place and the most important information is front-loaded.

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

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

For a tool with 8 parameters, no output schema, and no annotations, it covers purpose, return shape, defaults, incremental hashing, and a prerequisite. It only lacks detail on the skeleton categories and a few auxiliary context parameters, which are not required for a first correct call.

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

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

Schema coverage is only 38%, and the description compensates for the most important parameters: workspace-vs-files choice, default token budget, and since_hash skip semantics. It leaves auxiliary parameters (stderr, active_file, user_prompt) unexplained, but the core invocation decisions are covered.

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 opening sentence names a specific verb and resource ('Shrink workspace files into AST-valid skeletons') and lists the output categories, so an agent knows what the tool produces. It does not explicitly contrast itself with siblings such as hexum_expand, though 'before reading a repo' gives some positioning.

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 this before reading a repo' gives a clear trigger, and the workspace-vs-files preference with a server-visibility condition is actionable routing. There is also a conditional prerequisite to call hexum_skill first, but no explicit when-not-to-use guidance for the other 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?

No annotations are present, so the description carries the full behavioral burden. It discloses reading architecture.hexum, conditionally writing the skill file when missing, and returning SKILL.md body plus write path. However, it omits the upsert side effect of passing intensity and leaves 'follow it' vague.

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

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

Four sentences with no filler: purpose, mechanism, return value, and usage timing are each covered once. The most important information is front-loaded.

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

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

The description covers the return value, conditional write behavior, and when to call the tool. But with no output schema and two undocumented parameters, the missing meaning of files and workspace plus the ambiguous 'follow it' 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 only 50%: files and workspace have no schema descriptions. The tool description does not explain either parameter, and its mention of intensity largely repeats the schema. It fails to compensate for the undocumented parameters.

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

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

States a specific verb and resource: 'Install or switch the Hexum reply skill.' It also positions the tool as a prerequisite for other Hexum tools, which distinguishes it from the check/control/review sibling tools.

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

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

Gives an explicit timing rule: 'Call this before other Hexum tools when the skill is not installed.' It also explains the intensity override option. It does not name sibling alternatives or state when not to call, so it stops short of a 5.

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

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

With no annotations, the description carries the full burden of disclosing behavior. 'AST-valid write' and 'replace' indicate mutation and AST preservation, but the description does not disclose side effects, file persistence, error behavior, reversibility, or validation details. For a write tool, this is a significant transparency 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?

The description is a single, focused sentence with no filler. It front-loads the tool's nature ('Small AST-valid write') and then gives the two usage modes clearly. It could be slightly more structured, but it earns its length.

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

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

The tool has 7 parameters, no annotations, and no output schema, yet the description is quite brief. It omits the required file_path semantics, optional node_kind/column behavior, return values, error behavior, and relationship to sibling tools. This is insufficient for an agent to use the tool confidently in varied situations.

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

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

Schema description coverage is only 14%, so the description must compensate. It usefully explains the symbol_name + new_implementation pairing and the line + new_source pairing, but it leaves file_path, column, and node_kind unexplained. The description adds some meaning beyond the schema but does not fully cover all parameters.

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

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

The description states a specific verb and resource ('AST-valid write') and gives two concrete modes: replacing a symbol or replacing the node at a line. This makes the tool's purpose reasonably clear, though it does not explicitly distinguish it from siblings like hexum_expand or hexum_shrink.

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 provides no guidance on when to use hexum_splice versus its sibling tools. It only explains internal parameter modes ('Pass symbol_name + new_implementation... or line + new_source...'), which is not the same as selecting the right tool among alternatives.

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