Server Quality Checklist

Tool Scores

• get_statusA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description must itself indicate behavior. It conveys an aggregate, read-style report of current memory state, but it does not explicitly state side-effect safety, freshness semantics, or whether it is an inexpensive index read versus a scan. This is adequate but not richly 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?

  A single, front-loaded sentence that states the operation and the breakdown dimensions without filler. Every word contributes to the agent's understanding.

  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 one-parameter read-only status tool, the description explains the core return value (node counts grouped by kind and source) even without an output schema. It is slightly incomplete because 'kind' and 'source' are not enumerated, but the overall contract is clear.

  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 already describes projectRoot as an absolute path to the repository root with 100% coverage, so the description does not need to repeat it. The description adds no extra parameter-level detail, keeping this at the baseline for complete 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 uses a specific verb ('Report') and a specific resource ('how many nodes NexusMem currently remembers for a repository'), and the 'broken down by kind and source' detail makes it clearly a counts/status operation rather than a list or mutation. This differentiates it from sibling tools that list, search, sync, or resolve.

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

  Usage Guidelines2/5

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

  No guidance is given about when to choose get_status over list_recent_memory, search_memory, or list_stale_suggestions, and there are no exclusions or prerequisites. The usage context must be inferred entirely from the word 'Report.'

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

• search_memoryA
  4/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 behavioral disclosure burden. It does reveal a key trait—output is a token-budgeted, ranked context block rather than raw results—and lists data sources. Yet it does not state whether the operation is read-only, whether special permissions are required, or how edge cases like the asOf semantics behave, leaving some ambiguity.

  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 two sentences, front-loaded with the verb and resource, and packs in the content-type list and the critical behavioral contrast at the end. Every clause adds value, with no redundancy or filler.

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

  Completeness4/5

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

  For a complex search tool with no output schema, the description covers the core semantics: what is searched, what is returned, and the ranked/budgeted nature of the result. It doesn't detail the exact structure of the context block or error conditions, but the high-level guidance is 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.

  Parameters3/5

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

  The schema provides 100% description coverage for all five parameters, so the description need not add much. It echoes the 'token-budgeted' notion from the schema but does not elaborate on parameter constraints or relationships. The baseline of 3 is appropriate since the schema already carries the heavy lifting.

  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 resource ('NexMem-tracked repository's remembered history'), then enumerates the exact content domains covered (git commits, diffs, shell commands, docs, transcripts, issue/PR threads). It also clarifies the return type is a token-budgeted ranked context block, which differentiates it from sibling tools like list_recent_memory even without naming them.

  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 clearly communicates the intended use—searching a repository's remembered history—and lays out the breadth of content searched, which helps an agent decide when to invoke it. However, it does not explicitly contrast with sibling tools or state when NOT to use it, so it falls short of the top score.

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

• resolve_stale_suggestionA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of disclosing behavior. It clearly states that 'accept' never deletes the candidate, only down-weights it, and that 'dismiss' stops resurfacing without altering ranking. It also cross-references an equivalent command for familiarity, which adds useful 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?

  Two sentences carry substantial meaning with no filler. The accept behavior is explained first, dismiss second, and the key caveat ('never deletes it') is included immediately for the more consequential action.

  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 four parameters and no output schema, the description covers the essential operational semantics and side effects. It does not describe return values or error cases, but that gap is minor because the primary behavior and parameter roles are clearly articulated.

  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 adds some relational meaning by explaining that 'accept' links candidateId to againstId, but this largely mirrors what the schema already states for each parameter.

  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 states a clear verb ('resolve') and resource (contradiction/stale suggestion), then specifies the two concrete actions 'accept' and 'dismiss' with their distinct effects. This differentiates it from sibling tools like list_stale_suggestions, which would only surface the suggestions rather than act on them.

  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 clear context for when each action is appropriate: 'accept' writes a supersede link and affects ranking, while 'dismiss' silences the suggestion without changing ranking. It implies the tool is used after suggestions are surfaced, but it does not explicitly name the alternative or state when not 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.

• list_recent_memoryA
  4.3/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full behavioral burden. It discloses ordering (newest first), chronological (not relevance) nature, and conditionality of some item types. It implies read-only behavior through 'list' but doesn't explicitly state safety. This is solid coverage beyond the schema, though it could mention the return format or potential errors.

  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 two sentences, front-loads the main action, then details item types, and finishes with a comparison. It is information-dense with minimal fluff. Could be slightly tighter by trimming the category list, but it's well-structured and efficient.

  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 list tool with no output schema, the description conveys what the tool does, scope, and ordering. It doesn't describe the shape of returned items (e.g., timestamps, types), which might be needed, but given the simple purpose and full schema coverage, it is nearly complete. Minor gap on return structure prevents a 5.

  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 both limit and projectRoot are already well documented. The description adds no param-specific clarifications beyond the schema; it reinforces the overall behavior (e.g., 'newest first') but doesn't explain how limit interacts with ordering. Baseline 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 states the exact purpose: listing the most recently remembered items for a NexusMem-tracked repository, and enumerates the item types. It explicitly contrasts with search_memory by noting it is chronological, not relevance-ranked, so the tool is unambiguously distinguished from its sibling.

  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 gives explicit guidance on when to use this tool versus an alternative: 'use search_memory instead for a specific question.' It also notes conditional inclusion ('if enabled' for certain data types), clarifying scope. This is direct and actionable.

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

• sync_projectA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description discloses critical behavior: pruning is an irreversible full wipe of that source, is dry-run unless yes is true, and only includes conversation/issue history if enabled. It stops short of describing normal-sync idempotency or outputs, but the destructive-path details are well covered.

  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 whole definition is one dense sentence, but it front-loads the primary sync purpose and packs prune behavior into the second half without redundancy. It could be split into clearer sentences, but nothing is wasted.

  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 4-parameter tool with no output schema or annotations, the description covers the main action, the alternate destructive modes, the confirmation flag, and dry-run behavior. It leaves minor details unexplored (e.g., sync merge semantics), but an agent has enough to invoke it correctly.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3; the description adds value by explaining the relationship between pruneSource, pruneStaleShell, and yes (dry-run unless confirmed) and by illustrating what counts as a dead source. This goes beyond the field-level 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 opens with a specific verb and resource: ingest new git, diff, shell, docs, and optionally conversation/issue history into the NexusMem local database. It also clearly distinguishes the alternate prune mode from normal syncing, so an agent can tell it apart from the read/search siblings.

  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 clear context: use normal sync to add history, or pass pruneSource/pruneStaleShell when the goal is to delete a dead source's nodes. It does not explicitly compare against sibling tools, but the mode guidance is unambiguous and sufficient.

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

• list_stale_suggestionsA
  4.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 disclosing side effects. It explicitly states 'Nothing has been written yet', making clear this is a non-mutating listing operation, and it describes the state of the items being listed as open, unactioned candidates.

  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: it front-loads the core operation, then adds source, safety, and alternative routing in a single efficient sentence. Every clause 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?

  For a simple list operation with a fully documented two-parameter schema, the description covers what is listed, how the candidates arise, that no write occurs, and where to go next. There is no critical missing context an agent needs to invoke it correctly.

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

  Parameters3/5

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

  The input schema already provides 100% parameter documentation: projectRoot as absolute path and limit with default/ordering semantics. The description adds no additional parameter-level detail, so it meets the baseline but does not exceed it.

  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 names a specific verb ('List') and resource ('open contradiction verdicts for a NexusMem-tracked repository'), and clarifies that these are candidates flagged by a known command or by sync. It explicitly distinguishes itself from resolve_stale_suggestion by stating that no action has been taken yet.

  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 gives clear context for when this tool is relevant: open contradiction candidates from 'nexusmem stale --check-contradictions' or automatic sync. It also directs acting on a suggestion to resolve_stale_suggestion, but it does not spell out when not to use the tool versus other sibling list/search tools.

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