Server Quality Checklist

Tool Scores

• memory_scope_enableA
  3.7/5.0
  Behavior3/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 discloses that the tool re-enables a scope and that the effect is session-scoped, which is useful context. However, it does not mention edge cases such as attempting to re-enable an already-enabled scope, invalid scope identifiers, or whether the action is reversible. The description offers the basic behavior but lacks depth.

  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 a single, front-loaded sentence: 'Re-enable a previously disabled scope for this session.' It is concise, contains no filler, and communicates the essential purpose immediately. Every word contributes to the meaning.

  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?

  For a tool with one required parameter, no annotations, and an output schema (not shown), the description is minimally adequate. It clarifies the core operation and session scoping, but it does not explain what a 'scope' is, how to reference it, or what error conditions may arise. The presence of an output schema mitigates the need to describe return values, but there is still ambiguity around scope semantics and edge cases.

  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 schema has one required parameter 'scope' with no description (0% coverage). The description implies that the parameter is the identifier of the previously disabled scope, giving it some meaning. However, it does not specify the expected format (e.g., name vs. ID), whether there are constraints, or how the scope value relates to other memory tools. It adds minimal semantic value beyond 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 clearly states the action: 'Re-enable a previously disabled scope for this session.' It specifies a precise verb (re-enable), the resource (scope), and contextual constraints (previously disabled, session-scoped). This distinguishes it from its sibling tool memory_scope_disable, which 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.

  Usage Guidelines3/5

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

  The description implies usage after a scope has been disabled (it references 'previously disabled scope'), but it does not explicitly state when to use this tool versus alternatives, nor does it name the inverse sibling (memory_scope_disable). There is no guidance on prerequisites or conditions when not to use it. The context is implied but not fully elaborated.

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

• memory_listA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden and discloses key behaviors: default returns cheap summaries, with_bodies inlines full bodies (potentially costly), and the context bloat risk is highlighted. It does not explicitly state read-only status or error handling, but the warnings are valuable.

  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 four sentences, all information-dense. It front-loads the core purpose, then covers default behavior, the with_bodies trade-off, and filtering. No wasted words.

  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 adds essential context about default vs with_bodies return shapes and the risk of pulling all memories, which is helpful even with an output schema present. It doesn't mention pagination or response size limits, but for a small-store tool the guidance is adequate.

  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?

  The schema provides only types and defaults with no descriptions (0% coverage). The description enriches both parameters: with_bodies is explained with trade-offs (avoids multiple round trips vs context bloat) and scopes is described as a filter. This exceeds the schema's information substantially.

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

  Purpose4/5

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

  The description clearly states the tool lists active memories with a specific verb and resource. It distinguishes itself by describing the default one-line summary format, which implies a triage-oriented list operation, but does not explicitly name sibling tools like memory_show or memory_search.

  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 gives explicit guidance on when to use with_bodies and warns against casual use due to context bloat. It also advises using scopes for subset filtering. While it doesn't directly reference alternatives like memory_search, it provides clear situational usage guidance for all parameters.

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

• memory_scope_disableA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the transparency burden. It discloses the session-scoped effect, which tools are affected (memory_search and memory_list), and the reset behavior on server restart. This goes well beyond the bare schema and gives the agent a clear mental model, though it doesn't mention idempotency or error cases.

  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?

  Three concise sentences: what it does, the effect, and the persistence. The most critical information is front-loaded in the first sentence, with no filler or repetition. Every sentence adds value.

  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?

  The description fully covers the tool's purpose, effect on subsequent operations (memory_search/memory_list), the use case, and the reset boundary. Since an output schema exists, return values don't need to be described. It is complete for a simple state-changing operation with one parameter.

  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 schema provides only a string property with no description, and the description doesn't explicitly define the format or valid values for 'scope'. However, it does clarify the semantic role ('memories tagged with this scope'), which lets the agent infer that scope is a label. For a single parameter this is adequate but not deeply explanatory.

  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 ('Disable') and names the resource ('a scope') with explicit scoping ('for the rest of this session'). It clearly distinguishes from sibling tools, especially memory_scope_enable, by stating the opposite action. The effect on other tools (memory_search, memory_list) is precisely described.

  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 a concrete usage trigger ('when the user says “this is unrelated to project X”') and clarifies session-only behavior with reset on restart. It does not explicitly mention when not to use or directly name memory_scope_enable as the alternative, but the contrast is strongly implied.

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

• memory_write_cancelA
  4.5/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It goes beyond the basic action by disclosing TTL expiration, the behavior when the ID never existed, and the returned `existed=False` field. This is transparent for a cancellation operation.

  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?

  Two sentences, zero waste. The main action is stated first, then the parameter source, then the expiration behavior. Ideal size for the information provided.

  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?

  The tool is simple (one parameter, no nested objects) and the description fully explains what to pass and what to expect in edge cases. An output schema exists, so return values are already structured, and the description adds the necessary nuance.

  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 0%, so the description must compensate. It explains that `pending_id` comes from the original write response, which is crucial context not in the schema. For a single parameter, this is sufficient guidance.

  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 ('Drop') and resource ('a pending memory_write') and clearly states the action is cancellation without committing. It distinguishes from sibling tools like memory_write_confirm (which commits) and memory_write (which creates the pending write).

  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 explains when to use the tool ('Pass the pending_id from the original write response') and provides essential context (1-hour expiration). It doesn't explicitly name alternatives or exclusions, but the sibling tool names imply these, and the context is clear enough for an agent to select this tool for cancelling pending writes.

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

• memory_showA
  4.6/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 thoroughly explains the response's staleness signals, including conditional commit_drift behavior (only when caller is inside the origin repo), the meaning of path_drift, and the effect of memory_update on verification state. This is far beyond a basic fetch and gives the agent actionable insight.

  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 longer than average, but every sentence earns its place: it explains the purpose, describes the response fields, and gives actionable follow-up advice. The use of bullet-like formatting improves scannability. It is dense but not wasteful, earning a 4 rather than a 5.

  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 having only one parameter and an output schema that presumably describes return fields, the description adds critical interpretive context: how to interpret staleness signals, when commit_drift is present, and what to do in each scenario. This makes the tool's behavior and workflow complete for an agent, with no significant gaps.

  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 0%, but there is only one parameter (id) of type string. The description says 'by id' but does not specify where the id comes from or its format. However, the context of memory_search implies the id originates from search results. Since the parameter is simple and the description is not misleading, a score of 3 is appropriate.

  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 action and resource: 'Fetch a single memory's full content by id.' It clearly distinguishes this from sibling tools like memory_search by noting it is typically used after a search snippet looks relevant, making its role in the workflow explicit.

  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 usage context: 'Typically used after a memory_search snippet looks relevant.' It also gives conditional next steps—using memory_verify if the content holds, memory_update if drifted—and warns to spot-check before relying. This is clear when-to-use and alternative guidance.

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

• memory_write_confirmA
  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 full burden, and it delivers. It discloses expiry, the cases that can fire (expired vs. never-existed), re-gated outcomes (duplicate, previously_removed, credential_warning), and that the staged write survives with pending_retained: true. This is rich behavioral detail beyond a simple commit operation.

  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 moderately long but every sentence adds essential information: the commit action, the pending_id source, expiry, re-gating cases, and survival behavior. No fluff, but it could be slightly more concise by grouping related facts. Overall, efficient and well-structured.

  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 complexity and the presence of an output schema, the description covers the main behavioral aspects: what triggers the commit, possible outcomes, and the effects on the staged write. It doesn't explain the output schema itself (not required) but provides enough context to use the tool correctly. Slightly missing is the exact meaning of 'committed' versus other outcomes, but that's implied.

  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 sole parameter pending_id has no schema description (0% coverage), but the description explains it comes from the memory_write response that returned 'pending'. This adds meaningful context to an otherwise bare string parameter, though it doesn't specify format or constraints. Given the single parameter, this is sufficient.

  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: 'Commit a memory_write that returned status='pending''. This clearly states the tool's action and target, distinguishing it from siblings like memory_write_cancel. The mention of pending_id further clarifies its role as a confirmation step.

  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 states when to use the tool (after a memory_write returned 'pending'), and provides guidance on alternatives: 'memory_write_cancel or resolve the match' when the staged write survives. It also warns about the 1-hour expiry and possible re-gated outcomes, giving clear context for decision-making.

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

• memory_audit_turnA
  4.8/5.0
  Behavior5/5

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

  With no annotations, the description carries full responsibility. It discloses side effects ('emits turn_audited always, plus search_miss when miss'), scoping behavior ('auto-scopes to the caller's repo'), the miss detection logic, and return values (MissReport with verdict). This is highly transparent.

  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 dense but every sentence earns its place. It opens with the most critical warning ('Not for in-conversation use'), then covers mechanics, scoping, return, and side effects in three sentences with no 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?

  Despite complexity (telemetry, hooks, side effects, output schema), the description covers all necessary aspects: invocation constraints, probe behavior, scoping, miss criteria, events, and return type. It even summarizes verdict values, making it complete even without reading the 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 0%, so the description must explain parameters. It does so effectively: 'for `user_message` (`assistant_response` optional)' and 'within `lookback_seconds` (default 60)' explains the role and default of each parameter, adding meaning beyond the raw 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 clearly states the tool's purpose with specific verbs: 'Runs the search probe', 'checks whether a retrieval event fired', 'Returns a MissReport'. It distinguishes from siblings by explicitly noting it is 'not for in-conversation use' and is dispatched by the Stop hook, not meant for direct model invocation.

  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 when NOT to use it ('The model should never call this directly') and when it is used (dispatched by end-of-turn Stop hook). However, it does not explicitly name an alternative tool for direct memory search, though the reference to `memory_search` as the probe implies it.

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

• memory_removeA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description fully discloses the tool's behavior: files are moved to .tombstones/ with removal reason and session id, never hard-deleted. It also reveals downstream effects (searchable tombstones, removed_matches on memory_write) and reversibility via memory_restore, providing rich operational detail.

  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 yet information-dense, with each sentence adding value. It opens with the core action, then explains mechanism, use case, searchability, and undo—achieving completeness without unnecessary words.

  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 and the lack of annotations, the description covers the full lifecycle: what happens on removal, where data goes, how it can be searched, how it affects memory_write, and how to undo. It is self-contained and leaves no critical gaps for an agent to safely invoke the tool.

  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 0%, and the description compensates by explaining that 'reason' is the removal reason stored in the tombstone. However, 'id' is only implicitly understood as the memory identifier; the description could explicitly map both parameters. Still, it adds meaningful context beyond the bare 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 'Tombstone a memory,' a specific verb and resource, and distinguishes it from hard deletion by explaining the tombstone mechanism. It also clearly states when to use it ('when a stored fact is wrong or no longer relevant'), setting it apart from siblings like memory_update.

  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 usage context: use when a fact is wrong or irrelevant. It names alternatives and complements (memory_restore for undo, memory_list_tombstones for searching) and explains how tombstones surface via memory_write, giving the agent clear guidance on selecting this tool.

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

• memory_scope_overviewA
  4.9/5.0
  Behavior5/5

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

  With no annotations, the description supplies extensive behavioral details: cheapness, field semantics, filtering rules, special cases like null on first session, and effects of session-disabled scopes. It goes far beyond what annotations would provide, covering nuances like silent_misses deduplication and tombstone exclusion.

  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 long but packed with necessary detail about the complex return object. It opens with a one-line summary and then structures field explanations, though a more formal layout could improve scanability. Every sentence serves a purpose, but the density is high.

  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 presence of an output schema, the description goes beyond simply listing returns by explaining how to interpret and branch on each field. It covers edge cases (null first session, filtered vs absolute counts) and operational guidance (curation cues, pending write expiry), making it fully contextual for an agent.

  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?

  The schema provides no description for auto_scope, but the description explains default scoping to the caller's repository and how to opt into a cross-project view with auto_scope=False. It also notes global pass-through for memories without origin, effectively documenting the parameter's behavior.

  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 identifies the tool as a 'Cheap session-start hint' providing per-scope counts without bodies/ids/summaries. It distinguishes itself from memory_search by advising to skip searches when total is 0, making its purpose and scope unique among siblings.

  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 instructs to call once at conversation start and provides conditional logic for skipping memory_search. Also explains when to set auto_scope=False for cross-project views, giving clear context for usage.

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

• episode_handoffA
  5/5.0
  Behavior5/5

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

  With no annotations, the description bears full responsibility. It discloses auto-resolution logic, implicit filters (worktree equality, disabled_scopes cascade), return structure, note semantics (including that note never means 'wrote no journal'), and episode ordering/cap. This goes far beyond a simple 'read' statement and covers edge cases.

  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?

  Long but purposeful; front-loaded with the primary action, then structured details on parameters, return values, and alternatives. Every sentence adds detail needed to use the tool safely. 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?

  The tool has complex behavior with two parameters, an output schema, and no annotations. The description covers purpose, usage, return contract, and edge cases. It is self-sufficient for correct invocation and interpretation.

  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?

  Input schema has zero descriptions for its two parameters. The description explains max_episodes (default 5, cap 50) and prior_session_id (auto-resolve behavior, override use case). This compensates fully for schema gaps.

  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+resource+scope: 'Read the most-recent journal takeaways from a prior session in this worktree.' It distinguishes itself from siblings by referencing episode_search and memory_search as alternatives, and by positioning itself as the episode counterpart to memory. This is a clear, non-tautological statement.

  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 directs to 'Call this FIRST at a /loop iteration entry' and contrasts with memory_search. Provides when-not: 'For ad-hoc lookup of an older session's journal, prefer episode_search with an explicit parent_session_id.' Also explains when to pass prior_session_id explicitly. Comprehensive usage guidance.

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

• episode_promoteA
  5/5.0
  Behavior5/5

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

  Discloses critical side effects: successful commit deletes the source episode; pending holds it for memory_write_confirm; other non-committed statuses leave it untouched. Also explains body default behavior and return shape, which goes well beyond the absence of annotations.

  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 organized in clear paragraphs and a parameter list, with every sentence delivering necessary detail. No fluff or repetition; it is appropriately sized for a tool with complex side effects and routing.

  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 annotations, the description covers all important operational contexts: routing through memory_write, all possible statuses and their effects, body default logic, and the output shape. The presence of an output schema reduces the need to explain return types, but the description still adds the extra promoted_from_episode_id field.

  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?

  Although the schema has no property descriptions, the description compensates fully by explaining each parameter: episode_id is a ULID, scopes required, category default 'fact', confidence/source standard fields, and use_body behavior. This adds significant meaning beyond the bare 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 'Promote a journal entry (episode) into a durable memory,' which uses a specific verb and resource. It further clarifies the relationship to memory_write, distinguishing this tool from sibling tools like episode_write or memory_search.

  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 'Use this when an iteration's takeaway turns out to be a fact worth keeping across sessions' and contrasts with 'Loop/working state belongs in episodes.' This provides clear when-to-use guidance and implies alternatives like episode_write for transient state.

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

• episode_searchA
  5/5.0
  Behavior5/5

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

  With no annotations, the description fully bears the burden of disclosing behavior. It explains ordering (oldest-first within most-recent-N window), max_results overflow behavior (keeps MOST-RECENT N), worktree scoping nuances (permissive, when it passes through), explicit filters never being worktree-filtered, and the effect of `include_bodies`. This is exceptionally transparent.

  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?

  Although lengthy, the description is densely packed with necessary information. It is structured with clear sections (purpose, return shape, worktree scoping, parameters) and front-loaded with the core purpose. Every sentence adds technical value; there is no fluff or repetition of schema defaults.

  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 (8 parameters, no annotations, sibling distinctions) the description is remarkably complete. It covers return shape, ordering, scoping rules, parameter semantics, and alternative tool selection. An agent has everything needed 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.

  Parameters5/5

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

  Schema coverage is 0%, so the description compensates fully. Each of the 8 parameters is explained with its meaning, default, and behavior, including compositional relationships (e.g., `parent_session_id` composes with `swarm_id`) and edge cases (unknown `ids` are absent, not an error). This goes far beyond the raw 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 a specific verb+resource: 'Cross-session lookup for journal-shaped entries (episodes).' It immediately distinguishes itself from sibling tools by noting it is NOT ranked and explicitly contrasts with `episode_handoff` for the loop-iteration case, making its role 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: 'For the loop-iteration-entry case prefer `episode_handoff`' and explains cross-session vs. single-session contexts. It also details when to use explicit filters (`swarm_id`, `parent_session_id`, `ids`) to bypass worktree scoping, giving clear decision criteria for alternatives.

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

• episode_writeA
  5/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries the full burden. It discloses key behavioral traits: episodes are not durable facts, the durability gate does not apply, a 30-day TTL, storage path, invisibility to memory tools, pruning of prior sessions, and even the corruption risk from oversized takeaway/scopes which would make episodes vanish despite returning 'committed'.

  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 but every sentence earns its place. It is front-loaded with the core purpose, then structured into usage guidance, storage/lifetime, visibility, return value, and parameter details with bullet examples. No fluff or 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?

  With 4 parameters, no annotations, and an output schema described in text, the description covers all necessary context: storage path, TTL, durability semantics, return fields (including pruned_sessions), and parameter constraints. It is fully self-sufficient 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.

  Parameters5/5

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

  Schema coverage is 0%, but the description richly explains each parameter: body (required, markdown, capped), swarm_id (multi-agent fan-in, distinction from predecessor link), takeaway (one-sentence summary, frontmatter cap, corruption risk), and scopes (empty valid, cap, serialization risk). This goes far beyond the bare 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 a specific verb+resource: 'Append a journal-shaped entry for the current session.' It clearly distinguishes from sibling memory/episode tools by stating that episodes are a sibling tier, not a memory category, and that they are invisible to memory_search/memory_health/memory_list.

  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 this tool: 'Use this for content memory_write would reject as transient' with concrete bullet examples. Also names alternatives: 'Surface them via episode_handoff at iteration entry or episode_search for cross-session lookup' and 'Promote a takeaway to durable memory via episode_promote'.

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

• memory_record_useA
  5/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses side effects: demotion under `outcome_demotion`, unresolved-contradiction flag, audit-only for `corrected`, and the auto-applied default. It also explains `claim_excerpts` constraints (empty strings rejected) and their surfacing in `recent_negative_outcomes`.

  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?

  Although long, the description is well-structured with a markdown table and bullet list. The core purpose is front-loaded, and every sentence adds value, making the length justified.

  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?

  The description covers the decision process, side effects, parameter constraints, and edge cases. With an output schema present, return values are unnecessary to explain. It is complete for the tool's complexity.

  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?

  The schema has no parameter descriptions (0% coverage), so the description fully compensates. The outcome table defines meaningful values, `claim_excerpts` gets detailed parallel-list semantics, and constraints (length limits, None vs empty) are explained.

  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: 'Override the auto-applied outcome.' It explains default behavior and when to call, distinguishing it from siblings that modify memory content. The table of outcomes further clarifies its specific scope.

  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 says 'only call this tool when the model needs to record one of the three actionable outcomes below' and explains that the common case handles itself. It also notes that explicit `applied` is rarely needed, giving clear when-to/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.

• memory_searchA
  5/5.0
  Behavior5/5

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

  With no annotations, the description carries full behavioral disclosure. It reveals automatic outcome recording, mandatory announcement when hits shape replies, deterministic lexical ranking, auto-scope filtering behavior, and detailed branch-on field semantics (relevance tiers, staleness verdicts, drift counts). This is exactly the kind of behavioral transparency an agent needs to anticipate side effects and follow-up actions.

  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 lengthy but every sentence earns its place: no schema repetition, no fluff. It is front-loaded with purpose and usage, then organized into return fields, parameters, and post-call side effects. The structure aids skimming while maintaining density of unique, decision-critical information.

  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 (7 params, 0% schema coverage, no annotations, plus extensive return-field branching), the description is remarkably complete. It covers all parameters, return behavior, side effects, usage edge cases, and sibling alternatives. The output schema already handles return value details, so the description need not duplicate that. No significant gap remains.

  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 0%, so the description must compensate, and it does comprehensively. For every parameter, it adds actionable semantics: query advises using nouns as 'the lever', max_results indicates default 5 and cap 50 (schema says null), auto_scope explains global pass-through, since_prior_session explains the intra-session diff and how to distinguish 'nothing new' from 'no baseline', and mode enumerates options with default behavior. This fully compensates for the bare 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 clearly states 'Search stored memories' with a specific verb and resource, and immediately distinguishes this tool from siblings with 'Default: do NOT call — reach for it only when...', positioning memory_search as a fallback for contextual recall rather than a general-purpose search. This contrasts sharply with sibling tools like memory_list and memory_show.

  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 ('reach for it only when the user references shared context you lack'), names alternatives ('call episode_handoff instead' for prior iterations, 'memory_record_use to override' for outcome overrides), and references memory_scope_overview for disambiguating empty results. This is model-level usage guidance that goes far beyond a simple 'when you need to search.'

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

• memory_updateA
  5/5.0
  Behavior5/5

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

  With no annotations, the description carries full behavioral transparency and does so thoroughly. It discloses side effects (clearing last_verified_at and claims), replace semantics for scopes/links, warning triggers and acknowledgment flags, and the stale-status retry behavior. This is rich, non-obvious information 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.

  Conciseness5/5

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

  The description is long but appropriately sized for the tool's complexity. It front-loads the most impactful side effect first, then moves from purpose to parameters to return behavior, using clear section separators. It closes with 'docs/api.md carries the rest' to avoid unnecessary bloat.

  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 10-parameter complexity and no annotations, the description is remarkably complete. It covers all parameters, warnings, concurrency behavior, link type definitions, and even the stale return condition. With an output schema available for return structure, no critical information is missing for safe invocation.

  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?

  The schema provides zero descriptions for its 10 parameters, so the description must and does fully compensate. It explains each parameter's role, allowed values (e.g., confidence low/medium/high), special constraints (user-inference rejected), array replace semantics, and the meaning of each acknowledgment flag.

  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 'Refine an existing memory in place' with a specific verb and resource, and explicitly positions it as the preferred alternative to memory_remove + memory_write when correcting a stored fact. This distinguishes it from siblings and makes its 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?

  It explicitly recommends using this tool over memory_remove + memory_write for corrections, explains what it preserves, and includes a concrete exclusion: 'user-inference is REJECTED here' because updates lack the write flow's pending-confirm gate. It also advises calling memory_verify after body edits, offering clear when-to-use guidance.

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

• memory_verifyA
  5/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 and excels: it discloses idempotency, REPLACE-not-append list semantics, refusal conditions for absent paths and false claims, the stale status when another agent verifies first, and the side effect of resolving a `record_use(contradicted)` flag. These are meaningful behavioral details beyond what the schema provides.

  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 but every sentence earns its place given the tool's subtle semantics. It front-loads the core purpose and side effect, uses paragraph breaks and bullet-style parameter explanations, and avoids irrelevant 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?

  Despite having no annotations and seven parameters, the description is complete: it covers parameter semantics, refusal behavior, idempotency, interaction with memory_update, stale-status responses, and a health-flag side effect. The output schema exists, so return-value detail is not required, but the description adds extra return context with status='stale' and the hint to re-fetch.

  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 description coverage is 0%, so the description must compensate and does. It explains every parameter's role: `verified_paths` as the only attestation read by drift legs, `verified_commits`/`verified_versions` as audit-only, `verified_absent_paths` as intentional absence, and `claims` as memory_write-compatible syntax. It also clarifies `None` vs `[]` vs populated list semantics.

  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: 'Bump `last_verified_at` to now after spot-checking that a memory's claims still match reality.' It clearly distinguishes memory_verify from memory_update by explaining that verifying does not bump `updated`, while memory_update does not bump `last_verified_at`.

  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 when-to-use and when-not-to-use guidance: use after spot-checking, use verified_paths when the memory cites paths, never use verified_absent_paths for real drift, and re-verify after memory_update because it clears last_verified_at. It also names the sibling alternative memory_update, making the boundary unambiguous.

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

• memory_writeA
  5/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, and it does so thoroughly. It explains return statuses, deduplication behavior, pending user-inference claims, groundedness gating, drift monitoring, curation hints, and override flags. It even discloses that misattribution 'sticks' and that the user gets veto power, which is valuable behavioral context.

  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, but the tool is complex with 14 parameters and many return statuses. It is well-structured with clear sections: intro, parameters, return statuses, and curation hint. It is front-loaded with the core purpose and every sentence adds necessary operational detail; there is no filler or 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 the tool's complexity, the description is remarkably complete. It covers all major behaviors, return statuses, edge cases, override mechanisms, and even a passive curation notification. The output schema exists, but the description goes beyond it by explaining the meaning of each status and the conditions under which each is returned.

  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 description coverage is 0%, so the description must compensate for all 14 parameters. It explains content, scopes, category with subcategories, confidence, source, claims, groundedness_check, source_transcript, acknowledge_ungrounded, acknowledge_user_claim, and force=True overrides. It maps each return status back to relevant acknowledge_* flags, providing meaning far beyond the bare 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 a specific verb and resource: 'Create a new memory.' It clearly states when to call it ('Call PROACTIVELY when something durable enters the conversation') and distinguishes it from related tools by referencing memory_write_confirm, memory_write_cancel, memory_health, memory_remove, and memory_verify. This is a strong, unambiguous purpose statement.

  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?

  Explicit usage guidance is provided: 'aggressive writing is safe; the guardrails below catch bad writes.' It also gives category-specific guidance, warns against the catch-all 'general' scope, and explains when to use memory_write_confirm/cancel for user-inference claims. The description names alternatives for resolving issues, making the when-to-use decision clear.

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