Server Quality Checklist

Tool Scores

• commits_for_sessionA
  3.9/5.0
  Behavior4/5

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

  The description discloses a notable side effect: 'Its poisoning gate may quarantine the newest eligible unsafe linked session summary.' This goes beyond the annotations' destructiveHint: true by specifying what may be quarantined. It also clarifies that the tool does not guess intent when no link exists, adding behavioral nuance beyond the structured fields.

  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 concise at three sentences, front-loaded with the primary purpose. The second and third sentences add important behavioral context about the poisoning gate and non-guessing behavior, though some jargon ('poisoning gate', 'remem') could be clearer. Overall, it earns its place without excessive length.

  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 tool with an output schema and well-documented parameters, the description provides sufficient context by covering purpose, side effects, and return details. It lacks explicit usage guidance or exclusions, but given the presence of annotations and schema, the completeness is strong. The side-effect disclosure is particularly valuable.

  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 the schema already documents all parameters. The description does not add additional parameter-level meaning beyond what the schema provides, aside from mentioning the return of link evidence and git metadata, which is output-oriented rather than parameter-oriented.

  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 function: 'List git commits linked to a content session ID or remem memory session ID.' This uses a specific verb ('List') and resource ('git commits'), scoped by session ID. It also distinguishes from sibling tools like lookup_commit by clarifying it returns link evidence and does not guess commit intent when no link exists.

  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 for retrieving commits associated with a session, but it does not explicitly state when to use this tool versus alternatives. There are no exclusions or alternative tool names mentioned, so the guidance is indirect rather than explicit.

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

• lookup_commitA
  4.2/5.0
  Behavior4/5

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

  Annotations already signal destructive capability (destructiveHint=true). The description adds specificity about a poisoning gate that may quarantine an unsafe linked session summary, and clarifies the response separates git vs memory-derived data. This provides valuable context beyond the annotations, though the exact conditions of quarantine are not detailed.

  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 three sentences, each covering distinct information: core purpose, a mutation caveat, and response structure. No fluff, front-loaded with the primary verb and resource. 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 output schema exists, the description doesn't need to detail return values. It covers prerequisites (SHA), the potential side-effect (quarantine), and the response separation. It's adequate, though 'poisoning gate' could use unpacking for full clarity.

  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 coverage is 100%, so the baseline is 3. The description adds minimal extra meaning beyond the schema, only restating that lookup is by full or short SHA, which the schema already states. No additional parameter-specific semantics are introduced.

  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 lookup operation for git commit metadata and linked memory sessions, keyed by SHA. It distinguishes this from sibling tools by highlighting the separation of git metadata from memory-derived summaries, preventing inference of missing links.

  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?

  It implies the primary use case: when you have a full or short SHA and need commit metadata plus linked memory sessions. However, it does not explicitly compare against alternative tools or state when not to use it, 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.

• list_raw_sessionsA
  4.3/5.0
  Behavior4/5

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

  Annotations already declare read-only, non-destructive, and idempotent behavior. The description adds behavioral context by describing grouping, computed fields (first/last epoch, message count), and sampling of role=user messages, which goes beyond the schema and annotations. It doesn't mention pagination or limits, but for a read-only list endpoint, this is sufficient.

  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 that front-load the action, specify the output fields, and provide a use case. No filler; 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 tool has rich annotations, full schema descriptions, and an output schema. The description covers purpose, usage, and output format (matching a CLI command), making it complete for a read-only list tool.

  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%, with each parameter fully documented. The description does not add additional parameter-specific semantics beyond the schema, so the baseline 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 clearly states the tool lists sessions with raw archive messages within a time window, specifying the grouping key (source_root, project, session_id) and included fields. The verb 'list' and specific resource make it distinct from sibling tools like search_raw or timeline.

  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 a use case: 'Use for recap-style summaries of what happened in a period.' However, it does not mention when not to use it or name alternative tools, so it's not fully differentiating.

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

• search_rawA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. It adds valuable context: results are 'untreated conversation content — expect noise' and explains the raw archive's role in guaranteeing searchability even when summarize/promote skip a turn. This goes beyond the structured annotations without contradicting them.

  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 sentences, each earning its place: purpose, when-to-use, and behavioral expectations. No fluff, front-loaded with the core action, and well-structured for quick comprehension.

  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?

  With an output schema present, return values are covered. The description explains the tool's niche within the broader toolset (raw vs curated), the data scope ('every user/assistant turn captured by the Stop hook'), and the noise caveat. This is sufficient for a search tool, though it could briefly mention the supported filters (time, branch, project) to aid in selecting parameters, but the schema already covers those.

  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 the parameters are fully documented in the schema. The description adds high-level context (raw FTS, bypasses curation) but does not elaborate on individual parameters beyond what the schema already provides. At full schema coverage, a baseline 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 uses a specific verb ('Search') and clearly identifies the resource ('raw archive of every user/assistant turn captured by the Stop hook'). It explicitly contrasts with the sibling tool `search`, noting when to use each, which fully distinguishes it from alternatives.

  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 this tool: 'when `search` returns no curated match or you need to recall a literal phrase from past chats.' It also warns that results are untreated and noisy, setting clear expectations and contrasting with the curated `search` alternative.

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

• workstreamsA
  4.4/5.0
  Behavior5/5

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

  Beyond the read-only and idempotent annotations, the description discloses the return format (JSON array with status, progress, next action, blockers, timestamps) and error behavior (missing project or database failure). This adds valuable context not present in 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 three sentences, front-loaded with 'Read-only', and every sentence adds distinct information: scope, return shape, alternative tool, and error behavior. No filler words.

  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 purpose, alternatives, return format, and errors, but the mismatch between stated parameter requirements and the schema creates a significant gap in how to correctly invoke the tool. For a simple two-parameter tool, this inconsistency prevents full completeness.

  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, but the description introduces contradictory requirement claims: it states project is required and status optional, while the schema requires status and makes project optional. This misinformation reduces the semantic value provided 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 verb 'List' and resource 'workstreams', with explicit scoping by project and status. It distinguishes itself from update_workstream by stating it does not mutate data, making 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 directs users to update_workstream for mutations and states this tool does not create, update, or delete. It also mentions optional status filtering, giving clear context for when to use this tool.

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

• context_bundleA
  4.5/5.0
  Behavior5/5

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

  Description goes beyond annotations by detailing side effects: no foreground LLM/network call, canonical load failures become blocked audited bundles, and poisoning safety may quarantine rows, explicitly advising callers not to treat it as side-effect-free. This exceeds the destructiveHint annotation.

  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 somewhat verbose with repeated warnings (e.g., about historical support) but is organized and not excessively long. It conveys all necessary points without major redundancy.

  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, the description covers essential aspects: purpose, constraints, failure behavior, side effects, and what it returns. Since an output schema exists, not detailing return structure is acceptable. It is complete enough for agent usage.

  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 covers all parameters with descriptions, but the description adds meaningful context: project can be derived from cwd, role/risk/token budget have deterministic defaults, and as_of_epoch/include_superseded fail loudly until supported. This enriches parameter understanding 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 tool compiles a Context Bundle v1, specifying verb 'compile' and resource 'ContextBundle', and distinguishes it from sibling tools like timeline and 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?

  Provides usage context: experimental, requires schema_version=1, non-blank task, deterministic defaults, and explicitly warns about failure modes for historical pins and include_superseded=true. It also clarifies it uses the production SessionStart loader and performs no foreground LLM/network, but does not explicitly compare to alternatives.

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

• save_memoryA
  4.6/5.0
  Behavior5/5

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

  Annotations already mark destructiveHint=true and readOnlyHint=false; the description adds concrete behavioral context: using topic_key updates existing memory (overwrites) and by default writes a local markdown backup. This goes beyond the annotations and discloses side effects clearly. No contradiction.

  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 well-structured: opening purpose sentence, numbered trigger list, dedup note, and backup note. Every sentence adds value and the format is scannable, with 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?

  Given 17 parameters, full schema coverage, and an output schema, the description appropriately focuses on core usage triggers, dedup semantics, and side effects. It does not enumerate every parameter nuance, which is correctly delegated to the schema, leaving only minor gaps for edge-case parameters.

  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 reinforces topic_key semantics (dedup and update behavior) but does not materially add meaning beyond what the schema already provides for the other 16 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?

  The description clearly states the tool's action: 'Save a memory for future sessions' and lists four specific mandatory call scenarios (architecture decisions, bug fixes, discoveries, user preferences), which distinguishes it from sibling read tools like search and recall_user_context.

  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 'MUST be called after' guidance enumerates exactly when to use this tool, and the context implies it is for writes versus sibling read tools. It also gives conditional usage for topic_key dedup and local backup, offering practical alternatives.

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

• update_workstreamA
  4.6/5.0
  Behavior5/5

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

  Annotations only provide destructiveHint=true and readOnlyHint=false, but the description adds return semantics ('Returns a JSON object with id and updated'), no-match behavior, error cases (empty update, unknown status, database failure), and partial-update behavior (omitted fields remain unchanged). This significantly exceeds annotation coverage.

  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 carefully crafted sentences: first states the core action and constraints, second gives return behavior, third exclusions and errors. No redundant phrasing; all content earns its place.

  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?

  Covers prerequisites, field constraints, return value, no-match semantics, error conditions, and scope boundaries. Thoroughly complete for a 4-param tool with an output schema, even though the parameter dependency rule is incorrect.

  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?

  The description's rule 'At least one of status, next_action, or blockers is required' conflicts with the schema's required array, which mandates status. This misleads agents into thinking they can omit status if another field is provided, contradicting the schema and causing a validation error. Schema coverage is 100%, but the added dependency rule is inaccurate.

  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 'Mutates one existing workstream by id,' a specific verb and resource, and explicitly contrasts with create/delete and read operations via 'Use workstreams to list/read rows first' and 'does not create or delete workstreams.' This clearly distinguishes it from sibling tools like workstreams.

  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 conditions: at least one of status/next_action/blockers required, omitted fields unchanged, and status enum values. It also names the alternative for reading (workstreams) and excludes create/delete operations, making when-to-use clear.

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

• govern_memoryA
  4.7/5.0
  Behavior5/5

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

  Discloses important behavioral traits beyond annotations: the operation is auditable, requires explicit confirmation and reason for destructive actions, and never deletes raw archive data. This adds significant context beyond the destructiveHint annotation.

  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, front-loaded with the primary actions, followed by usage prerequisites and a critical scope limitation. No wasted 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 complexity of 8 parameters and an output schema, the description covers the core workflow and safety constraints. The existence of an output schema means return values don't need to be explained. The description is complete enough for an agent to use the tool effectively.

  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 covers 100% of parameters, and the description adds meaning to key parameters like dry_run (preview affected IDs) and confirm_destructive (required for non-dry-run mutations), plus the rationale for 'reason'. This goes beyond the baseline for full schema coverage.

  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 function with specific verbs: 'delete, reject, or mark curated memories stale.' It identifies the resource (curated memories) and distinguishes it from sibling tools like save_memory or 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?

  Provides clear usage guidance: use dry_run=true first to preview, and non-dry-run mutations require confirm_destructive=true and an explicit reason. While it doesn't explicitly mention alternatives, the context and prerequisites are well-defined.

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

• timeline_reportA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the description's 'Read-only' restates these. However, it adds useful behavioral context by disclosing that database failures return a tool error, which is not present in the annotations. This provides a clearer failure model.

  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 concise and well-structured: it opens with purpose, explains parameter behavior, then gives usage guidance and error behavior. Every sentence carries relevant information with no redundancy or 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?

  For a tool with two parameters and no output schema, the description covers the core functionality, output format (Markdown), parameter effects, usage recommendations, and failure behavior. It is complete enough for an agent to select and invoke 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 both parameters with descriptions (100% coverage). The description adds value by clarifying the 'full' flag's semantics: 'full defaults to false for the compact report; full=true adds the detailed timeline and monthly breakdown.' This goes beyond the schema's wording by distinguishing compact vs. detailed reports and describing the overall report content.

  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 a specific action ('Generate an aggregated Markdown report') with a defined scope (project activity history, type distribution, Token ROI analysis). It explicitly distinguishes itself from sibling tools by stating 'Use this for project-level reporting, not observation lookup; use timeline for chronological context around one observation.'

  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 gives explicit usage guidance: 'Use this for project-level reporting, not observation lookup; use timeline for chronological context around one observation.' It also explains the effect of the 'full' parameter and notes failure behavior, covering both when to use and when not to use it.

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

• current_stateA
  4.9/5.0
  Behavior5/5

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

  Beyond the readOnly/idempotent/destructive hints already in annotations, the description discloses the possible resolution statuses, the output fields (answer, compact history, why edges), the non-blank constraint, and error conditions ('Invalid input or database failures return a tool error').

  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 three sentences, front-loaded with 'Read-only', and every sentence adds value—no repetition of schema or annotations. It is concise yet information-dense.

  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 resolution tool with six parameters and an output schema, the description covers purpose, usage context, input constraints, output structure, error behavior, and sibling relationships. The output schema supplies the remaining structural details, so the description is complete.

  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% with per-parameter descriptions. The description adds contextual meaning by noting that 'state_key must be non-blank' and that the filter parameters 'narrow the resolution', which goes beyond the schema's literal field descriptions.

  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 the verb ('Resolve') and resource ('one stable state_key') and the output shape (JSON object with statuses). It distinguishes from siblings by explicitly naming search and timeline as alternatives.

  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 instead of search ('Use this instead of search when the durable key is known') and when to use timeline ('use timeline for chronological observation context'). It also notes the required non-blank state_key and filter behavior.

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

• get_observationsA
  4.9/5.0
  Behavior5/5

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

  Discloses side effects (recording last-accessed metadata) and error conditions (unsupported sources, missing IDs, detail-read failures, memory access-update failures). It also explains best-effort behavior for observation source. The annotations (destructiveHint: true) are consistent with this write behavior, and the description enriches them.

  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 paragraph but well-structured: purpose, usage, source semantics, and error conditions. Every sentence adds critical information; no wasted words. It is dense yet readable.

  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 complexity (4 params, side effects, multiple sources, error paths), the description covers all essential aspects: what it does, when to use, side effects, and failure behavior. An output schema exists to handle return details, so no need to describe them here.

  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 significant meaning for the 'source' parameter by detailing default, return types, and update success/failure semantics. It also explains that 'ids' come from search results, adding context beyond the schema. Other parameters are adequately covered by 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 fetches full details for explicit IDs and records last-accessed metadata. It explicitly differentiates from discovery tools by saying 'Use after search, not for discovery', distinguishing it from siblings like search and timeline.

  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 guidance: 'Use after search, not for discovery'. It instructs to pass selected IDs and the exact source from search results, and explains the difference between source='memory' and source='observation'. This is clear and actionable.

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

• recall_user_contextA
  4.9/5.0
  Behavior5/5

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

  Annotations include destructiveHint=true and readOnlyHint=false, and the description aligns by disclosing the poisoning gate may quarantine unsafe legacy/session summaries. It also reveals scope-resolution precedence (project > cwd > process working directory), output structure, and error conditions. This goes well beyond the annotations to explain behavior and 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.

  Conciseness5/5

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

  The description is front-loaded with the primary purpose, followed by critical behavioral notes, scope rules, output summary, alternatives, and error conditions. Each sentence is packed with necessary information without redundancy. It is appropriately sized for a tool with 13 parameters and meaningful side effects.

  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 complexity (13 params, output schema, annotations), the description covers the key aspects: what it assembles, the poisoning side effect, scope handling, output format, alternatives, and failure modes. It does not need to enumerate every parameter since the schema is thorough, and the output schema exists to define return values.

  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 value by clarifying the interplay between project, cwd, and the current process working directory, and by emphasizing the non-blank requirement for query. It does not detail every parameter, but the schema already describes each one; the description meaningfully enhances scope-related 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?

  The description starts with 'Assemble task-aware user context from safe claims...' which provides a specific verb (assemble) and resource (user context) plus the source material. It distinguishes from siblings by naming search and current_state and explaining the different selection strategy. This is a clear, non-tautological statement of 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?

  The description explicitly says 'Use search for exhaustive memory matches and current_state for one exact stable key; this tool selects a bounded context bundle instead.' This names two alternatives and gives clear when-to-use guidance. It also notes the requirement for a non-blank query, which acts as a precondition.

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

• timelineA
  4.9/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, openWorldHint, idempotentHint, destructiveHint), the description reveals important behavioral traits: anchor takes precedence over query, depth_before/after default to 5, project limits both anchor lookup and results, and error conditions (missing anchors/queries, no match, DB failures). This is substantial context beyond structured 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 dense but efficient: four sentences conveying read-only behavior, return type, conditional anchor/query, defaults, project scope, sibling alternatives, and error handling. Every sentence carries critical information with 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?

  Given the output schema exists and parameters are optional, the description covers all key aspects: purpose, input semantics, defaults, error behavior, and alternatives. It leaves no significant gaps for the agent to misuse 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?

  The schema covers all 5 parameters with descriptions (100% coverage), but the description adds relational semantics not present in the schema, such as anchor/query precedence and the effect of project on both lookup and results. This helps the agent understand how parameters interact, exceeding the baseline for fully documented schemas.

  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 'Return a JSON array of observations before and after one center point' with a specific verb and resource, and it explicitly distinguishes this tool from siblings such as timeline_report, search, and current_state by naming alternatives.

  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 provides explicit usage guidance: 'Use this for local chronological context around an observation' and contrasts with timeline_report, search, and current_state. It also warns that missing anchors/queries, no match, or database failures return a tool error, which helps set expectations for correct usage.

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

• searchA
  5/5.0
  Behavior5/5

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

  Even with readOnlyHint and idempotentHint annotations, the description adds rich behavioral detail: task-aware RetrievalPlan compilation, fallback behavior, error handling, pagination defaults, and return format metadata. It discloses how invalid combinations or database failures behave.

  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 due to the tool's complexity, but every sentence provides distinct value: purpose, advanced modes, return format, alternatives, constraints, and error handling. 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?

  Given the 15 optional parameters, output schema, and sibling tools, the description covers return format, pagination, error conditions, fallback semantics, and alternatives. It is sufficient for an agent to know when and how to use 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 covers all 15 parameters at 100%, but the description adds cross-parameter context not in the schema: limit/offset defaults, query optionality, task_intent high-level behavior, and the constraint that explain and multi_hop require a non-blank query. It also references get_observations for follow-up.

  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 'Read-only. Search or list curated memories' with a specific verb and resource. It distinguishes from siblings by explicitly naming current_state, timeline, and search_raw as alternatives for different use cases.

  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 current_state when an exact stable state_key is known, timeline for chronological observation context, and search_raw for literal chat recall.' Also specifies constraints like explain/multi_hop requiring a non-blank query and explain not combinable with multi_hop=true.

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