pre_commit_check

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It transparently explains that the tool combines three internal signals (anti_patterns_check, mem_for_files, mem_verify) without invoking them separately, and clarifies the meaning of parameters like `block_on` and `anchored_blocks`. However, it does not mention side effects on state (e.g., whether memories are modified), auth requirements, or rate limits. It does not contradict any annotations since none exist.

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 well-structured with a clear lead sentence, bulleted list of internal signals, and parameter definitions. It is front-loaded with the core purpose. The description of the return value is brief but adequate. The only minor inefficiency is perhaps repeating the phrase 'anti_patterns_check' in the semantic parameter description, but overall it is efficient and scannable.

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

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

Given the tool's moderate complexity (5 parameters, 3 internal signals), the description covers the purpose, usage, parameter semantics, and output format. No output schema exists, so the description provides a clear return structure (`should_block`, `summary`, etc.). It lacks details on edge cases (e.g., what happens if both `diff` and `paths` are omitted) and does not specify cost or latency implications of the three internal checks, which could be useful for an agent deciding whether to call this tool. Still, it is largely complete for most usage scenarios.

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

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

Schema description coverage is 100%, so the schema already documents all 5 parameters, including defaults and enums. The description adds value by explaining the blocking logic for `block_on` (e.g., 'any' blocks on any warning) and the `anchored_blocks` detailed behavior (token overlap, semantic threshold). This goes beyond the schema by providing the agent with decision guidance, earning a score above baseline 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 clearly states the tool's purpose: 'One-shot should I block this commit? check', specifying the verb ('check'), resource ('commit'), and scope ('combines three signals'). It distinguishes itself from siblings by noting that the internal signals (anti_patterns_check, mem_for_files, mem_verify) are not invoked separately, making it clear this is a composite tool rather than a memory or code search 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?

The description explicitly states when to use this tool: 'USE FROM A GIT HOOK or before finalizing a non-trivial change.' It also hints that `hivelore enforce check` is an alternative for git-hook gates, providing context but not confusing the agent. No direct sibling tool does the same thing, so the guidelines are clear and no exclusions are needed beyond what's stated.

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