Server Quality Checklist

Tool Scores

• mem_triedA
  3.5/5.0
  Behavior3/5

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

  Discloses useful behavioral traits: 'Auto-validated (no approval cycle)' and 'Surfaced FIRST in future get_briefing calls.' However, the description incorrectly states scope default as 'team (default)' while the schema says it defaults to personal unless a sensor is attached. This contradiction undermines transparency, and the main description omits the sensor validation behavior entirely.

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

  Conciseness3/5

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

  The description is well-structured with clear sections (purpose, usage, behavior, params, returns) and front-loaded intent. However, the PARAMETERS list is incomplete and contains an inaccurate scope default, which reduces the quality of the structure. It's not overlong, but the misinformation detracts from its conciseness.

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

  Completeness2/5

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

  The tool has 9 parameters and a complex nested sensor object, but the description omits the sensor feature entirely and misstates scope default. It covers the simple failure-recording case well but is incomplete for advanced usage. Given the schema exists, it doesn't need to duplicate every detail, but it should at least be consistent and hint at the sensor capability.

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

  Parameters2/5

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

  Schema coverage is 100%, so baseline is 3. The description's PARAMETERS section adds concise semantics for what/why_failed/instead/paths, but it omits tags, author, module, and sensor. More critically, it states 'scope — team (default) | personal', which contradicts the schema's 'Defaults to personal — EXCEPT when a one-shot sensor is attached: ... defaults to team.' This misinformation actively misleads agents.

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

  Purpose5/5

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

  The description opens with 'Record a FAILED approach so future agents don't repeat the same mistake,' which clearly identifies the verb (record), resource (failed approach), and intended purpose. This instantly distinguishes it from sibling tools like mem_save or get_briefing by focusing on negative knowledge.

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

  Usage Guidelines4/5

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

  Provides explicit guidance: 'USE THIS IMMEDIATELY when you try something and it doesn't work' and explains the value ('saves hours of debugging'). It does not, however, mention when not to use it or directly compare to alternatives like mem_save, so it falls short of a perfect score.

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

• mem_searchA
  4.1/5.0
  Behavior4/5

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

  Given no annotations, the description carries full burden. It discloses search-mode fallback (AND→OR), lexical ranking behavior, the requirement for an embeddings index, and session_recap exclusion. However, it does not mention the side effect of track=true incrementing read_count (though schema covers this), and it contains an incorrect default limit (10 vs schema's 20), slightly clouding behavioral expectations.

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

  Conciseness4/5

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

  The description is structured with clear headings (USE WHEN, SEARCH MODES, PARAMETERS, RETURNS) and front-loads the purpose. It is longer than the minimal case but each section earns its place given the tool's complexity. Slight redundancy exists in the PARAMETERS section but it remains readable.

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

  Completeness3/5

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

  The description covers the main search modes, usage context, and return shape, which is significant given no output schema. However, it omits several schema parameters (status, module, exclude_rejected, include_session_recap) and contains an incorrect default limit, making it not fully reliable for complete understanding without the schema.

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

  Parameters2/5

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

  Schema coverage is 100%, so baseline is 3. The description's PARAMETERS section adds a few interactions (e.g., lexical_rank ignored when semantic is true) but includes a serious factual error: limit default is stated as 10 while schema says 20. It also describes query as 'natural language question', which could mislead in literal mode where substring matching is used. These inaccuracies degrade value below baseline.

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

  Purpose5/5

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

  The description opens with a clear verb+resource: 'Search memories by keyword or semantic similarity.' It further differentiates from siblings by stating 'USE WHEN you need to find a specific memory and don't know its id' and explicitly contrasts with get_briefing, making the tool's purpose unambiguous.

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

  Usage Guidelines5/5

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

  Provides explicit guidance: 'USE WHEN you need to find a specific memory and don't know its id' and directs to get_briefing for session onboarding. It also notes that semantic mode requires an embeddings index, setting clear prerequisites for choosing this mode over others.

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

• mem_session_endA
  4.1/5.0
  Behavior5/5

  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 the upserve behavior ('uses topic-upsert — one recap per scope is kept and updated in-place'), mentions that revision_count increments, and describes how get_briefing surfaces the latest recap. This goes beyond a simple write operation and gives the agent a clear mental model of side effects.

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

  Conciseness4/5

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

  The description is well-organized with clear sections (HOW IT WORKS, PARAMETERS, RETURNS) and front-loads the core purpose. It is somewhat long, but each section earns its place. The parameter list duplicates some schema information, but the added context (e.g., files_touched as staleness anchor) justifies the length. Minor redundancy prevents a 5.

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

  Completeness3/5

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

  The description covers usage, behavior, and the return shape, which is helpful given the absence of an output schema. However, it omits the 'module' parameter and fails to clarify the scope=module requirement, creating ambiguity about when that parameter is needed. This gap makes the description incomplete for a tool with 7 parameters and conditional requirements.

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

  Parameters2/5

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

  Although the schema coverage is 100%, the description's parameter section is misleading and incomplete. It lists scope as 'personal (default) | team' but omits the 'module' option present in the schema enum. It also drops the 'module' parameter entirely, which is required when scope=module. This introduces a conflict with the input schema and fails to add full semantic value.

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

  Purpose5/5

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

  The description clearly states the tool's purpose: 'Save an end-of-session recap so the NEXT session starts with fresh context.' It uses a specific action (save) on a specific resource (end-of-session recap) and explains the benefit. It also distinguishes itself from the autopilot auto-save and references get_briefing, setting it apart from sibling memory tools.

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

  Usage Guidelines4/5

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

  The description explicitly says 'CALL THIS before closing any significant working session' and contrasts manual use with the autopilot minimal automatic recap. This provides clear usage context. However, it does not explicitly name alternatives or exclusionary conditions (e.g., when not to use it), so it falls slightly 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.

• mem_getA
  4.2/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry the transparency burden. It conveys a read-only fetch operation implicitly via the verb 'Fetch' and lists the return fields, but it doesn't explicitly state that the tool has no side effects or how it behaves on an invalid/unknown id. This leaves some behavioral context unaddressed.

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

  Conciseness5/5

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

  The description is well-structured with distinct sections (purpose, usage when, parameters, returns) and is concise without fluff. Each line serves a clear function, and the key purpose is front-loaded, making it easy to parse quickly.

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

  Completeness4/5

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

  For a simple single-parameter fetch tool, the description covers the primary purpose, usage context, parameter format, and return fields. It lacks explicit error behavior or a note on idempotency, but given the tool's simplicity and the provided return schema detail, it is sufficiently complete for an agent to select and invoke it correctly.

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

  Parameters4/5

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

  The schema only says 'Memory id to fetch' for the id parameter, while the description clarifies that it must be a 'full id' and provides a concrete example format ('2026-04-28-gotcha-flyway-strict-no-ddl'). This adds meaningful parameter semantics beyond the schema, especially given the schema coverage is 100%.

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

  Purpose5/5

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

  The description opens with 'Fetch a single memory by its full id with all details,' a specific verb and resource that clearly defines the tool's scope. It distinguishes itself from sibling tools like mem_search by focusing on fetching a single memory by its unique full id, making its purpose unmistakable.

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

  Usage Guidelines4/5

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

  The description explicitly states 'USE WHEN get_briefing / mem_relevant_to / mem_search returned a compact hit and you need the full body, or when you know the exact id of a memory,' providing clear trigger conditions. It, however, doesn't formally exclude cases like needing to search without an id, so it stops short of fully explicit when-not-to-use guidance.

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

• scaffold_testA
  4.3/5.0
  Behavior4/5

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

  Despite having no annotations, the description discloses key behaviors: it produces a PENDING stub, does not arm a sensor, keeps the suite green, and is monorepo-aware. It also notes the dry-run 'write' parameter behavior. However, it doesn't discuss potential errors or overwrite semantics, so a 4 rather than 5.

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

  Conciseness4/5

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

  The description is well-structured: a clear opening sentence, a bolded usage directive, a non-goal clarification, and a concise parameter summary. It is longer than a single sentence but every line adds value; the only slight redundancy is repeating 'framework auto-detected' which already exists in the schema.

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

  Completeness4/5

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

  The description covers the tool's role, its place relative to propose_sensor, the pending-test behavior, and the return shape. It leaves out explanation of the 'style' and 'red_ref' parameters, but those are fully defined in the schema, so the agent can rely on the schema. Given no output schema, the return field list could be more detailed, but it's sufficient.

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

  Parameters3/5

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

  The input schema already documents all 7 parameters at 100% coverage, so the baseline is 3. The description adds only a brief list of four key params and some narrative around their purpose, but does not add meaning beyond the schema for the omitted ones (style, red_ref, reference). It does reinforce that framework auto-detects and write has a preview mode, matching the schema.

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

  Purpose5/5

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

  The description opens with 'Generate a PENDING post-incident test from a lesson (attempt/gotcha)' — a specific verb, resource, and state. It also distinguishes from propose_sensor by explicitly stating it does NOT arm a sensor, making its scope unambiguous.

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

  Usage Guidelines5/5

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

  The description provides explicit when-to-use guidance ('USE THIS right after mem_tried when the mistake is behavioural') and a clear exclusion ('It DOES NOT arm a sensor — propose_sensor stays the sole validated writer'). This gives an agent clear decision criteria among siblings.

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

• mem_updateA
  4.4/5.0
  Behavior4/5

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

  No annotations provided, so description carries full burden. It discloses in-place mutation, that id/usage history/read_count are preserved, that parameters replace existing values, and the return format. Lacks error conditions (e.g., what if memory doesn't exist) but sufficient for typical use.

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

  Conciseness5/5

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

  Extremely concise and well-structured: a one-sentence summary, usage guidelines paragraph, parameter list, and return format. Every sentence adds value; no filler.

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

  Completeness4/5

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

  For an 8-parameter mutation tool with no output schema and no annotations, the description covers purpose, usage, parameter replacement semantics, and return format. It could briefly note error conditions (e.g., memory not found) but is otherwise complete.

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

  Parameters3/5

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

  Schema description coverage is 100% (each parameter has a detailed description stating replacement semantics). The description adds a concise summary and groups parameters, but adds limited value beyond what the schema already provides.

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

  Purpose5/5

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

  The description clearly states the tool updates an existing memory in-place, specifying the exact components (body, tags, anchor). It contrasts with sibling mem_save for the topic-upsert pattern, providing clear differentiation.

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

  Usage Guidelines5/5

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

  Explicitly states when to use (memory exists, content outdated/incomplete) and when not to (evolving memories: use mem_save with topic key). Provides clear alternative, which is excellent guidance for an AI agent.

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

• code_mapA
  4.5/5.0
  Behavior4/5

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

  No annotations, so description carries full burden. It discloses the return shape (available flag, files with exports), the prerequisite (index already run), and behavior when the index is unavailable (run hivelore index code first). This gives strong context for a read-only lookup tool, though it doesn't discuss auth or rate limits.

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

  Conciseness5/5

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

  Well-structured with clear sections (description, usage note, tip, parameters, returns). Front-loaded purpose. Each sentence earns its place; the tip is genuinely useful. Slight redundancy with the PARAMETERS section duplicating schema, but not enough to penalize.

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

  Completeness5/5

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

  For a 5-parameter tool with no output schema, the description is complete: it provides the return shape, an availability flag with fallback instruction, and the required precondition. The schema handles token-budget details, so nothing critical is missing.

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

  Parameters4/5

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

  Schema description coverage is 100%, so baseline is 3. The description adds an example ('PaymentService'), clarifies partial-name matching, and includes the get_briefing auto-lookup tip, going beyond the schema for symbol and file parameters.

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

  Purpose5/5

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

  Clear verb+resource: 'Look up where symbols (classes, functions, interfaces) are defined in the codebase.' Distinct from grep and sibling code_search by explicitly saying 'USE INSTEAD OF grepping when you need to find where something lives.'

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

  Usage Guidelines4/5

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

  Explicit use case: 'USE INSTEAD OF grepping when you need to find where something lives.' Also mentions prerequisite (hivelore index) and a tip to include symbols in get_briefing. Could strengthen by explicitly naming sibling code_search as an alternative for full-text search, but this is already good.

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

• pre_commit_checkA
  4.5/5.0
  Behavior4/5

  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.

  Conciseness4/5

  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.

  Completeness4/5

  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.

  Parameters4/5

  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.

  Purpose5/5

  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.

  Usage Guidelines5/5

  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.

• code_searchA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden. It discloses the dependency on a pre-built index, the fallback notice if the index is missing, the return format (including `available`, `hits` with fields like file, name, kind, line, description, score), and the effect of `min_score` in dropping low-similarity hits. It also scopes the search to exported symbols only, which is non-obvious behavior.

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

  Conciseness5/5

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

  The description is well-structured and front-loaded: a crisp purpose statement, a usage rule with alternative, a prerequisite/fallback note, then compact PARAMETERS and RETURNS blocks. Every sentence contributes value, 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.

  Completeness5/5

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

  For a search tool with 3 parameters, no output schema, and no annotations, the description fully covers the essentials: what the tool does, when to use it, prerequisites, fallback behavior, parameter meanings, and return structure. It leaves no critical operational question unanswered.

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

  Parameters3/5

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

  Schema description coverage is 100%, so baseline is 3. The description's PARAMETERS section largely paraphrases the schema: examples for query and the min_score tip ('try 0.3+ for stricter') are already present in the schema. No new meaning is added beyond the structured definitions, so it stays at the baseline.

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

  Purpose5/5

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

  The description clearly states the tool performs 'Semantic search over the codebase' and 'finds exported symbols (functions, classes, interfaces) related to a natural-language query'. It distinguishes itself from blind grep, and in the context of siblings like code_map, it emphasizes natural-language search over exact matching, giving it a distinct purpose.

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

  Usage Guidelines5/5

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

  It explicitly says 'Replaces blind grep when you don't know the exact symbol name', providing a clear when-to-use scenario and an alternative. It also discloses a prerequisite ('Requires `hivelore index code-search` to have been run') and the fallback behavior when the index is missing, giving the agent clear conditionals.

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

• mem_relevant_toA
  4.7/5.0
  Behavior4/5

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

  Although no annotations exist to provide safety profile, the description discloses the ranking pipeline (anchor/module/literal/semantic), what it skips, and the return shape. It doesn't explicitly state 'read-only', but the retrieval nature is clear; slightly more detail on side effects would be ideal.

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

  Conciseness5/5

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

  The description is compact, front-loaded with the key differentiator, and uses a clean PARAMETERS block. Every sentence earns its place; no fluff.

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

  Completeness5/5

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

  Despite no output schema, the description includes a RETURNS section outlining the response shape. Combined with explicit workflow guidance and parameter clarifications, it covers the tool's role and behavior thoroughly.

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

  Parameters4/5

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

  Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'inherits get_briefing memory framing' for format, and clarifying the purpose of files ('surfaces anchored memories'). It supports the schema without redundancy.

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

  Purpose5/5

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

  The description uses a specific verb ('ranked memories for a task') and clearly distinguishes from siblings by naming get_briefing as an alternative ('use instead of...'). It also explains the niche ('when project context is already loaded and you only want the relevant memory layer').

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

  Usage Guidelines5/5

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

  Explicitly describes when to use this vs get_briefing, and places it in a progressive disclosure sequence ('Second step... after get_briefing... then mem_get'). Also clarifies what is skipped, leaving no ambiguity about scope.

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

• mem_saveA
  4.7/5.0
  Behavior4/5

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

  With no annotations provided, the description fully carries the transparency burden. It discloses upsert semantics via 'topic', dedup rejection for identical body content, a warning about immediately stale paths, and the return object shape. This is strong for a mutating tool, though it does not mention permission requirements.

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

  Conciseness5/5

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

  Well-structured with clear section labels (USE THIS WHEN, PARAMETERS, RETURNS, WARNING, DEDUP). The description is front-loaded with a one-sentence purpose, and each block adds necessary operational detail without redundancy.

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

  Completeness5/5

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

  Given 13 parameters and no output schema, the description compensates by specifying the return object, warning about stale paths, explaining dedup rejection, and clarifying scope semantics. The activation object is documented in the schema, so its absence from the description is acceptable.

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

  Parameters4/5

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

  The schema already provides 100% parameter descriptions, but the description adds meaningful semantics: slug format with a kebab-case example, scope audience definitions, topic's in-place update behavior, and a strong recommendation for paths. It omits minor parameters like tags/author, but the schema covers them adequately.

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

  Purpose5/5

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

  The description opens with 'Save a piece of knowledge as a persistent memory that survives across AI sessions,' a specific verb+object that clearly states what the tool does. It distinguishes itself from siblings by explicitly naming mem_tried as the alternative for failed approaches.

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

  Usage Guidelines5/5

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

  Provides a dedicated 'USE THIS WHEN' list (project conventions, architectural decisions, gotchas, domain terms) and a 'DO NOT USE' section pointing to mem_tried as the preferred alternative. It also gives situational advice for reactive code discoveries, making the decision boundary explicit.

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

• mem_verifyA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description carries the full burden. It discloses that the update parameter writes status back to disk, defines all three statuses (fresh, stale, anchorless), and explains the meanings of stale and anchorless. This is comprehensive behavioral disclosure.

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

  Conciseness5/5

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

  The description is well-structured with clear sections: purpose, USE WHEN, PARAMETERS, RETURNS. Every sentence provides necessary information without fluff, and the primary purpose is front-loaded.

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

  Completeness5/5

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

  Without an output schema, the description defines the exact return shape and all possible statuses. It covers both optional parameters, the automatic sync context, and the edge case of anchorless memories. This is complete enough for an agent to select and invoke the tool correctly.

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

  Parameters4/5

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

  The input schema already covers 100% of parameter descriptions. The description adds the key default that omitting id checks all memories, which is not in the schema. The update parameter is restated but adds no new meaning, so the added value is modest.

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

  Purpose5/5

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

  The description opens with a specific verb and resource: 'Check whether memory anchor paths and symbols still exist in the current code.' This clearly differentiates it from sibling tools like mem_get or mem_search, which retrieve memory content rather than validate existence.

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

  Usage Guidelines4/5

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

  Provides explicit USE WHEN scenarios: 'after a refactor' or 'to check all memories for staleness.' It also mentions that hivelore sync handles this automatically, giving context for when the tool might not be needed. However, it does not explicitly name alternatives or state when not to use the tool, 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.

• report_frictionA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden and delivers richly. It discloses that reports stay local, are not published, and are reviewed manually. It explains deduplication behavior via fingerprinting and the occurrence counting mechanism, and details the evidence bar where 'bug' requires a repro.

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

  Conciseness4/5

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

  The description is well-structured with clear sections and front-loaded purpose. It is thorough but not verbose, using bullet-like formatting. A slight deduction for length; while informative, it could be tightened slightly without losing clarity (e.g., 'EVIDENCE BAR' section could be more concise).

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

  Completeness5/5

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

  Given 6 parameters, 3 required, no output schema, no annotations, and complexity of deduplication/evidence rules, the description provides comprehensive coverage. It explains return fields, behavior, and constraints, making it complete enough for an agent to invoke correctly without gaps.

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

  Parameters4/5

  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 adds significant value by explaining each parameter's purpose in context (e.g., 'kind' enum meanings, 'surface' grouping logic, 'summary' as dedup key, 'repro' requirement for bugs), but some details like 'expected' and 'observed' are straightforward and the schema already describes them adequately.

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

  Purpose5/5

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

  The description clearly states the tool is for reporting friction with Hivelore itself, using specific verbs ('Tell', 'get in your way') and explicitly distinguishes it from sibling tools like mem_tried and mem_save, which are for project-level issues. The scope is unambiguous.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool (list of Hivelore-related issues) and when NOT to use it (project code issues), naming sibling alternatives (mem_tried, mem_save). It also covers deduplication and evidence requirements.

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

• propose_sensorA
  4.9/5.0
  Behavior5/5

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

  The description is exceptionally transparent: it discloses that proposals are validated before being trusted, rejected proposals are NOT written, and the return shape includes reason, guidance, self_check, and file_path. It also clarifies validation conditions (silent on correct code, fires on bad example) and the importance of the `absent` regex for discrimination. This is strong behavioral disclosure given no annotations are provided.

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

  Conciseness4/5

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

  The description is well-structured, front-loaded with purpose and usage, and each paragraph has a distinct role. However, the PARAMETERS section redundantly repeats 5 parameters' descriptions already present in the schema, adding some unnecessary length. Overall, it remains efficient and easy to scan.

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

  Completeness5/5

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

  For a tool with 15 parameters, no output schema, and nested objects, the description is remarkably complete. It covers purpose, when to use, validation rules, rejection behavior, return shape, and key parameter semantics. The schema handles the full parameter syntax, and the description provides the essential 'why' and 'how' context.

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

  Parameters5/5

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

  Even though the schema describes all 15 parameters with 100% coverage, the description adds significant conceptual meaning: it explains how `pattern` and `absent` work together, gives an example, and clarifies `bad_example` as proof and `severity` defaults. This goes beyond the schema's field descriptions, enriching the agent's understanding.

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

  Purpose5/5

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

  The description explicitly states the verb 'Propose' and the resource 'a discriminating sensor for a gotcha/attempt', and explains the user writes the pattern while Hivelore validates it. It also contrasts this with an advisory note, clearly establishing the tool's role and differentiating it from related memory operations like mem_save and mem_tried.

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

  Usage Guidelines5/5

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

  Directly instructs when to use: 'USE THIS right after mem_tried / mem_save on a gotcha whose mistake is detectable in code'. It also explains the goal (upgrading a warn sensor to a precise, promotable one) and provides validation criteria and guidance to call propose_sensor again if rejected.

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

• get_briefingA
  5/5.0
  Behavior5/5

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

  With no annotations, the description fully carries behavioral disclosure. It details the ordered returns, mandatory action_required protocol (stop and wait for human confirmation), confidence levels for memories, token-budget behavior, and warnings about autonomous actions on breaking changes. This is far beyond typical tool descriptions.

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

  Conciseness5/5

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

  The description is long relative to simple tools, but it is exceptionally well-structured with headers, bullet lists, and bold directives. Every sentence adds value: usage guidance, return order, protocol, key parameters, example, and confidence levels. Information is front-loaded with the most critical 'DEFAULT-FIRST' directive.

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

  Completeness5/5

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

  Given the tool's complexity (16 params, no output schema, no annotations), the description covers all necessary context: full return section ordering and priority, action-required handling, confidence levels, token budget behavior, and parameter semantics. It effectively substitutes for an output schema.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds strategic meaning beyond the schema: 'task — ALWAYS provide this' (critical usage rule), 'files — surfaces anchored memories', 'symbols — ... no grep needed', and 'budget_preset — scales max_tokens/memories/module contexts'. An example usage further clarifies parameter combination.

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

  Purpose5/5

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

  The description clearly specifies that get_briefing is the 'DEFAULT-FIRST' onboarding call for coding agents, aggregating all relevant repo context in one call. It distinguishes from siblings via 'Replaces 4–5 separate tool calls' and explicit direction to use mem_search/mem_get only for follow-up.

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

  Usage Guidelines5/5

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

  Gives explicit when-to-use guidance: 'call this BEFORE changing source or project config' and 'unless the developer explicitly opts out'. It also provides exclusions and alternatives, e.g., 'use mem_search / mem_get only for follow-up', and describes a progressive disclosure strategy.

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