Server Quality Checklist

Tool Scores

• vectr_reinstateA
  3.7/5.0
  Behavior3/5

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

  Annotations already provide idempotentHint=true, destructiveHint=false, and readOnlyHint=false. The description adds that original content is restored, which is useful but does not go beyond the safe profile established by annotations.

  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 a single sentence that front-loads the main action. However, the unclear phrase 'or a contradicts= write' slightly reduces clarity and conciseness.

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

  Completeness2/5

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

  The description lacks information about return values and error conditions. Given no output schema and the tool modifying state, this omission leaves the agent without needed context.

  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 both parameters documented. The tool description does not add additional meaning beyond what the schema provides, so 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 explicitly states 'Reverse a prior vectr_revoke' and explains that the note returns to active state with original content. This clearly distinguishes it from sibling tools like vectr_revoke and vectr_forget.

  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 tells when to use: to reverse a prior revoke. However, it does not explicitly state prerequisites (e.g., note must be revoked) or alternatives, though the context is clear.

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

• vectr_locateA
  4.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the absence of side effects is covered. The description adds that the tool returns file path, line number, and kind, which is useful but not behavioral. No additional traits (rate limits, auth needs) are disclosed, but the read-only nature is clear from 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 concise (3 sentences plus an example), front-loads the core purpose, and every sentence adds value. No redundant or wasteful language.

  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 has 3 parameters, no output schema, and annotations already cover read-only/idempotent, the description is fairly complete. It states the output format, provides usage guidance, and gives an example. Minor gap: no description of the 'limit' and 'caller_file' parameters beyond schema, but overall adequate.

  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 three parameters. The description provides an example using the 'name' parameter and implies case-sensitive partial match, but does not add significant new meaning beyond the schema. 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 clearly states the verb (locate), the resource (symbol definition), and the output (file path + line number + kind). It also explicitly distinguishes from siblings by stating when NOT to use it, listing alternatives vectr_search and vectr_trace.

  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 ('when you know the SYMBOL NAME but not which file it's in') and when-not-to-use criteria ('NOT when searching by concept/behaviour' and 'NOT when wanting call relationships'), with specific alternative tools named (vectr_search, vectr_trace).

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

• vectr_traceA
  4.4/5.0
  Behavior4/5

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

  The description adds value beyond the annotations by explaining that the tool traverses the call graph in both directions and showing an example output format. While the annotations already indicate it is read-only and idempotent, the description adds the behavioral detail of bidirectional traversal. A small gap is that it does not explicitly state that results are textual, but the example compensates.

  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 the primary usage condition, then describes the action, followed by two 'NOT' conditions with alternatives, and ends with an example. Every sentence adds value, and the critical information is front-loaded.

  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 is quite complete given the tool's complexity, the presence of annotations, and full schema coverage. It covers purpose, when to use/not use, and provides an example. However, it lacks an explicit statement that the output is a textual listing, though this is implied by the example. Overall, it provides sufficient context for an agent to use 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 input schema has 4 parameters with 100% description coverage, so the baseline is 3. The description does not add significant new information about parameters beyond what is in the schema, except for illustrating the 'name' parameter in the example. The schema already provides defaults, enums, and descriptions for 'limit', 'direction', and 'include_builtins', so the description is adequate but not exceptional.

  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: traversing the call graph for a known symbol name to understand its callers or callees before modification. It uses specific language ('traverses the call graph') and provides an example. It also explicitly distinguishes from siblings by stating when not to use it and which alternative tools to use instead.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use the tool ('know the SYMBOL NAME and need to understand its callers or callees before modifying it') and when not to use it ('when you don't know the symbol name yet — use vectr_search or vectr_locate first' and 'when you just want the definition location — use vectr_locate instead'). This gives clear decision criteria for tool selection.

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

• vectr_rememberA
  4.5/5.0
  Behavior5/5

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

  Adds meaningful behavioral context beyond annotations: persistence across context compaction and future sessions, <50ms retrieval performance, the token/turn cost of re-reading files, and a concrete corruption risk for long escape-dense strings passed as tool-call arguments. The content_file guidance further exposes an important operational behavior. No contradiction with readOnlyHint=false or destructiveHint=false.

  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?

  Dense and front-loaded, with the core purpose in the first sentence and concrete usage guidance immediately after. It is long, and the '<50ms' point is repeated somewhat redundantly, but most sentences earn their place by giving actionable guidance or rationale.

  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 write tool with no output schema and 16 parameters, the description covers the common path well: what to store, what not to store, how to handle large code-heavy bodies, and how to retrieve later. Advanced fields are delegated to the schema's rich parameter descriptions, which is acceptable; the only notable omission is describing what the tool returns (e.g. the new note_id), which would help with supersedes/contradicts chaining.

  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 genuine parameter-level guidance for content vs content_file, including the ~2KB threshold and mutual exclusivity, and connects content quality to future recall value. It does not systematically cover all 16 parameters, but the schema already documents those thoroughly and the description adds value where it matters most.

  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?

  States a specific action ('Save a working note and recall it on demand'), names the resource (vectr memory), and explicitly names the retrieval counterpart vectr_recall. It is clearly distinguishable from the read-side sibling and is not tautological or vague.

  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?

  Gives concrete when-to-use triggers: 'Use the moment you discover something non-obvious' with examples (file path, call pattern, gotcha, stub, progress), and explicitly says what NOT to store ('Do NOT store obvious or easily re-derivable facts'). It does not enumerate exclusions against related write tools such as vectr_pin or vectr_forget, but the timing and anti-pattern advice is strong enough to guide tool selection.

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

• vectr_pinA
  4.6/5.0
  Behavior5/5

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

  The description discloses non-obvious behavior beyond annotations: unconditional injection, no relevance scoring, never dropped for being off-topic, and a bounded number of directive+pinned notes allowed in this tier. It also makes clear that unpinning is possible via pinned=false. No contradiction with annotations is present.

  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 dense and well-structured, with the primary effect front-loaded. Each sentence contributes a distinct aspect: effect, use case, unpin method, resource bound, and equivalence with write-time pinning. It is slightly verbose but not redundant.

  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 two-parameter operation with no output schema, the description fully explains when to use it, what it does, and how to undo it. It also covers the resource-administration bound and equivalent alternative, leaving no practical gap for an agent 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?

  Schema description coverage is 100%, so the schema already documents note_id and pinned. The description's only added hint is 'Pass pinned=false to unpin,' which essentially restates the schema. Therefore, the description adds no significant value beyond the input schema, yielding the baseline 3.

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

  Purpose5/5

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

  The description uses a specific verb and resource: 'Pin a note' so it is 'injected on EVERY future vectr_recall(query=...) call'. It further distinguishes itself from the standing-rule directive role and from vectr_remember by explaining that this is for notes you don't want to reclassify.

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

  Usage Guidelines5/5

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

  It explicitly says when to use this tool: for a note that must never be missed by an unlucky query, and contrasts it with the kind='directive' role. It also names an alternative/equivalent approach: passing pin=true to vectr_remember at write time. The 'pin sparingly' caveat additionally guides usage.

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

• vectr_snapshotA
  4.6/5.0
  Behavior4/5

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

  Discloses that it creates a named checkpoint and that vectr_recall will return those notes later, but could mention if it overwrites existing snapshots or has other 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?

  Two sentences plus an exception note, front-loaded with the action, and every sentence adds necessary context without 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?

  Covers purpose, usage, and relation to vectr_recall well; lacks detail on multiple snapshots or behavior of calling again, but adequate for a simple 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?

  Adds value by explaining the label parameter's role and providing examples, while the schema already covers both parameters fully.

  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 defines the tool's action (sealing notes as a named checkpoint) and distinguishes it from sibling tools like vectr_recall by explaining that vectr_recall retrieves all notes regardless of snapshots.

  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 guidance on when to use (when storing multiple notes for a milestone) and when not to use (if only 1-2 notes, vectr_recall suffices), with specific label examples.

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

• vectr_anchorA
  4.7/5.0
  Behavior5/5

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

  Annotations already indicate idempotentHint=true and destructiveHint=false; the description adds important nuance by defining anchors as staleness probes rather than correctness claims, and by explaining that already-attached paths are reported back rather than duplicated. There is no contradiction with 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 front-loaded with the core action and then packs the alternative workflow, anchor semantics, and idempotency behavior into four dense sentences. Every sentence adds operational value without filler.

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

  Completeness5/5

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

  For a two-parameter tool with 100% schema coverage and idempotency annotation, the description covers the operation's purpose, when to use it, the meaning of anchors, and the behavior on repeated invocation. No critical missing information prevents an agent from calling 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 documents both required parameters with 100% coverage, including workspace-relative paths and the source of note_id. The description reinforces the semantics but does not need to add much 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 states a specific verb and resource: attach file paths to an existing note, with a clear purpose of flagging possibly-stale notes. It also distinguishes itself from re-storing with anchors/supersedes, helping an agent tell this operation apart from related vectr tools.

  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 frames the tool as 'the single-call replacement for re-storing with anchors=[...] and supersedes=<note_id>' and gives the trigger condition: when you notice afterwards that a note is about a specific process/config file. This is clear when-to-use guidance and implies when the alternative workflow would be preferred.

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

• vectr_evict_hintA
  4.7/5.0
  Behavior4/5

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

  Beyond annotations (readOnlyHint, idempotentHint), description adds that each chunk is re-fetchable with exact vectr_fetch keys, explaining the protocol relationship with vectr_remember. No contradictions.

  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?

  Four concise sentences with no waste. Front-loaded with purpose, then usage guidance, then protocol context, then limitations. Each 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?

  Given no parameters or output schema, description fully covers what the tool does, when to use it, its role in the protocol, and its limitations. Complete for this tool's simplicity.

  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?

  No parameters (0 params), so schema coverage is 100%. Description adds meaning about return value (list of chunks with re-fetch keys), exceeding baseline of 4 for zero-parameter tools.

  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?

  Description clearly states 'Lists the code chunks retrieved by THIS session that are safe to drop from context', with verb and specific resource. It distinguishes from sibling tools by positioning as the reverse signal in the vectr protocol.

  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 guidance: 'Use at the exploration → implementation transition, or when context pressure builds.' Also notes it's 'NOT needed on short sessions' and identifies when it's most useful.

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

• vectr_promoteA
  4.7/5.0
  Behavior4/5

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

  Description adds behavioral context beyond annotations: affirms only auto->agent transition, explains why human promotion is unavailable, and implies idempotency. Annotations already provide idempotentHint=true, so 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?

  Two sentences, front-loaded with purpose, no unnecessary words. 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?

  Fully explains scope, constraints, and rationale for a simple tool. No output schema needed; return behavior is not complex.

  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% and parameter descriptions exist. The description reinforces the 'to' parameter's constraint and rationale, adding meaning 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?

  Clearly states the action of promoting a note's trust class to 'agent', specifies the resource (auto-captured note), and distinguishes from other tools by noting it never promotes to human.

  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 (after reviewing and confirming a note) and when not to use (never to human), with reference to alternative user-side action for human endorsement.

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

• vectr_recallA
  4.7/5.0
  Behavior5/5

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

  Beyond the readOnly and idempotent annotations, the description details the two-tier recall, token-bounded index, sorting behaviors, boot mode, and note expansion. This adds significant behavioral transparency.

  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 yet highly efficient, front-loading the core purpose and then efficiently covering the two-tier recall, usage guidance, and key parameter hints without waste.

  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 (10 parameters, no output schema), the description fully explains the return format, recall hierarchy, filtering options, and usage context, leaving no significant gaps.

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

  Parameters4/5

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

  With 100% schema coverage, the baseline is 3. The description adds extra context for several parameters (e.g., query example, note_id ID source, sort_by chronological behavior), warranting a 4.

  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 retrieves notes from current or prior sessions, with a specific two-tier recall hierarchy (index vs full body). It uses specific verbs and resources, and the purpose is unambiguous.

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

  Usage Guidelines4/5

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

  The description advises when to use the tool (after confirming notes exist via vectr_status) and when not to (calling without query unless needed). It provides clear context but does not explicitly compare to sibling tools, slightly reducing the score.

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

• vectr_resumeA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint. The description adds detail on what is returned (note, snapshot, gotchas with anchors), providing additional transparency without contradicting 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?

  Two sentences, front-loaded purpose, 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?

  Given zero parameters, no output schema, and straightforward behavior, the description fully covers purpose, usage, and output. Nothing missing.

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

  Parameters4/5

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

  No input parameters, so the baseline is high (4). The description explains the tool's output and purpose, making up for the lack of param details.

  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 defines the tool as a one-call reorientation mechanism returning specific artifacts (current-task note, snapshot, gotchas). It uses a specific verb ('resume') and distinguishes from siblings like vectr_recall.

  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 call: 'at the start of a session or after a gap'. Also explains the benefit (avoid re-reading files) and contrasts with alternative vectr_recall.

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

• vectr_revokeA
  4.7/5.0
  Behavior5/5

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

  Annotations show destructiveHint=false and idempotentHint=true; description adds crucial behavioral context: note stays visible with deterrent framing, content replaced, reversible. No contradiction with 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?

  Description is front-loaded with purpose, then usage guidance, then alternatives. Every sentence earns its place; no fluff. Efficiently structured for agent comprehension.

  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 mutation tool with no output schema, description fully explains behavioral effects (deterrent display, content change), reversibility, and how it differs from siblings. Complete and self-contained.

  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% and both parameters are already well-described in the schema (reason shown verbatim, note_id from recall). The description does not add new information beyond what the schema provides, so baseline score applies.

  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?

  Clearly states the tool flags a note as WRONG without deleting it, distinguishing it from vectr_forget (erases) and vectr_remember (prefer when writing correction). Verb and resource are 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?

  Explicitly says use when 'you've confirmed a prior finding no longer holds' and advises preferring vectr_remember when recording a correction. Also mentions reversibility with vectr_reinstate, providing clear when-to-use and when-not-to-use.

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

• vectr_snapshot_listA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true. Description adds ordering ('newest first') which is extra behavioral info beyond annotations. No contradictions.

  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: first states purpose, second gives usage context. No redundancy, front-loaded with key action. Every sentence 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?

  Given no parameters, no output schema, and rich annotations, the description is complete. It covers purpose, usage timing, and ordering. No gaps identified.

  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?

  No parameters (0 params), schema coverage 100%. Baseline is 4 per instructions. Description correctly implies no input needed.

  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?

  Description clearly states the verb 'list', resource 'saved session snapshots', scope 'for this workspace', and ordering 'newest first'. It distinguishes from siblings like vectr_snapshot (create) and vectr_resume (restore) by specifying usage 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?

  Explicitly says when to use: 'at session start to find an existing checkpoint if vectr_recall returned nothing or if you want to resume a specific named session'. Provides clear conditions and reference to alternative tool.

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

• vectr_statusA
  4.7/5.0
  Behavior4/5

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

  Annotations already declare readOnly and idempotent hints. Description adds decision-making context and clarifies return field semantics, enhancing transparency beyond 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?

  Single paragraph, front-loaded with what it returns, then usage guidance. Every sentence provides value, 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 no parameters and no output schema, description fully explains return values and how to use them in context. Agent can determine when and how to 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?

  No parameters; schema coverage 100%. Description doesn't need to add parameter info. Baseline for 0 params is 4.

  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?

  Description clearly states it returns index health and notes_count. Specific verb 'Returns' and resource 'index health, notes_count'. Distinguishes from siblings by being the status/decision tool for vectr_recall.

  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 says when to use (start of session), provides conditional logic (notes_count > 0 vs == 0), warns against re-calling for auto-injected notes, and mentions utility when vectr_search returns nothing.

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

• vectr_fetchA
  4.8/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint and idempotentHint. The description adds that the operation is 'deterministic', 'no embedding, no rerank', and explains the id format 'file:start-end' from prior search results. No contradictions.

  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?

  Four tightly-packed sentences with zero waste. The most critical information (purpose and when to use) is front-loaded, followed by the id format reference and a clear exclusion statement.

  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?

  No output schema, but the tool's behavior is simple. The description covers purpose, usage context, parameter semantics, and safety (via annotations). It could optionally describe the return format, but the current content is sufficient given the low complexity.

  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 a description for the 'ids' parameter. The tool description adds valuable context about the id format and provenance ('exactly as shown in a prior search/locate/trace result'), going 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 'Deterministic re-fetch of a code chunk by its exact id' and distinguishes from siblings by explicitly naming vectr_search, vectr_locate, and vectr_trace for finding new content. The verb 're-fetch' and resource 'code chunk' are specific.

  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: 'restore a chunk that was cleared from your context' and when not to: 'NOT for finding NEW content — use vectr_search for that'. Provides concrete alternatives, making selection straightforward.

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

• vectr_mapA
  4.8/5.0
  Behavior5/5

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

  The description adds behavioral context beyond annotations: it explains that the tool returns a compact summary if a passport is saved, or raw metadata with instructions otherwise. It also states it does not read files. This aligns with readOnlyHint and idempotentHint without contradiction.

  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 front-loaded with the key use case and conditional behavior. While somewhat lengthy, every sentence provides essential information. It could be slightly more concise but is well-structured.

  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 conditional behavior and lack of output schema, the description thoroughly explains both possible outcomes and actionable next steps. It also mentions sibling tools for context, making it complete for the agent's decision-making.

  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 has zero parameters, so the description doesn't need to explain parameters. However, it adds meaningful context about the conditional behavior and return types, which compensates for the lack of parameters. A score of 4 is appropriate as it fully covers what the tool expects and does.

  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: to get a structural overview of an unfamiliar codebase at the start of a session. It specifies the output based on whether a passport is saved, distinguishing it from related tools like vectr_recall and vectr_status.

  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: it should be used at the start of a session on an unfamiliar codebase, and not when the codebase is already known. It also directs to call vectr_status first and mentions vectr_map_save as a follow-up if needed.

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

• vectr_searchA
  4.8/5.0
  Behavior4/5

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

  Annotations already indicate readOnly, idempotent, and not open world. The description adds that it returns function/class bodies with file paths and line numbers, and mentions the hybrid search algorithm, providing useful context beyond 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?

  Three sentences plus two 'NOT' conditions, no extraneous content. Front-loaded with purpose and key usage direction. Every sentence 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?

  Given no output schema, the description adequately explains return values (function/class bodies with file paths and line numbers). Combined with parameter guidance and behavioral transparency, it provides a complete picture for usage.

  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 100%, but the description adds significant value: explains query as natural language/code, notes that unindexed language returns no results and lists indexed languages, and provides detailed usage guidance for n_results with token cost implications.

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

  Purpose5/5

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

  The description clearly states the tool performs hybrid semantic + BM25 search for code by concept, behavior, or description. It distinguishes from sibling tools by specifying when not to use it (symbol name -> vectr_locate, call relationships -> vectr_trace).

  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 ('when you know WHAT... but not WHERE...') and when not to use, providing alternative tool names. Also includes parameter usage guidance, e.g., for n_results to prefer 1-2 for specific lookups.

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

• vectr_distillA
  4.9/5.0
  Behavior5/5

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

  Description discloses extensive behavioral details: token-bounded rendering, oldest-first ordering, batch cap, deduplication rules, and kind mapping. No contradiction with annotations (idempotentHint=true is consistent with idempotent dismiss).

  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?

  Description is verbose but well-structured with front-loaded purpose and numbered rules. Every sentence adds value, though could be slightly more concise.

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

  Completeness5/5

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

  Given tool complexity (multiple modes, rules, and integration with other tools), the description is remarkably complete. Covers all states: render, dismiss, and distiller rules. No output schema, but return value (rendered arcs) is implied.

  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 covers 100% of parameters with descriptions, but the description adds essential semantics: explains that dismiss and reason must be used together, provides examples, and clarifies behavior with no arguments.

  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?

  Description clearly states the tool reviews pending arcs (failure->success moments) and distills them into working-memory notes. It distinguishes from sibling 'vectr_remember' by positioning itself as the review/dismiss 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?

  Provides explicit guidance: call with no arguments to render arcs, call with dismiss+reason to reject, and detailed rules for when to keep vs dismiss. References alternatives like vectr_remember and vectr_recall for deduplication.

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

• vectr_ingest_tracesA
  4.9/5.0
  Behavior5/5

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

  Beyond annotations (which indicate mutation but not destructiveness), the description discloses that dynamic edges are stored with edge_type='dynamic' and appear as '(dynamic)' in results. It also warns about typos: unknown symbols are ingested but reported as warnings. No contradiction with annotations.

  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 a single paragraph that efficiently conveys purpose, usage, behavior, and parameter details with no fluff. It's front-loaded with the main action. Slight improvement could be breaking into sections, but it remains very concise.

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

  Completeness5/5

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

  Given that the tool has one parameter with nested objects and no output schema, the description covers the complete behavioral context: ingestion of dynamic edges, marking, warnings for unrecognized symbols, and when not to use. Nothing essential is missing.

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

  Parameters5/5

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

  Schema coverage is 100%, but the description adds meaning by explaining the event structure, noting optional fields (caller_file, caller_line), and describing behavior for unmatched symbols. This goes beyond the schema's parameter types.

  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 says 'Import runtime trace events into the symbol graph to enrich static call analysis,' using a specific verb and resource. It distinguishes from siblings by contrasting with static analysis (vectr_trace) and listing dynamic dispatch patterns (decorators, __getattr__, etc.) that only this tool handles.

  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: 'Use when you have runtime profiling data... that reveals dynamic dispatch patterns the static analyser cannot see.' Also gives a clear when-not: 'NOT needed if static analysis (vectr_trace) already shows the call relationships.' This is excellent guidance.

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

• vectr_supersedeA
  4.9/5.0
  Behavior5/5

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

  The description goes well beyond the annotations by explaining the observable effects: the note stops appearing in default recall/session-start, renders a '[superseded ...]' badge, is not marked wrong, never shows the revoked deterrent, and is reversible. This gives the agent a clear model of what the operation does and does not do.

  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 economical: it fronts the core scenario, then explains behavioral consequences, contrasts with vectr_revoke, and closes with parameter guidance and reversibility. Every sentence contributes distinct information with no repetition of the schema or annotations.

  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 three-parameter, non-destructive state-transition tool with rich annotations and a fully documented schema, the description supplies everything needed to invoke it correctly: the triggering condition, the exact note to mutate, the optional link to the replacement, the post-condition behavior, and the alternative tool in case of actual falsity.

  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 with descriptions, establishing a baseline of 3. The description adds meaningful usage semantics—particularly that superseded_by links the replacement that should have carried supersedes=<old id> and that omitting it means retiring with no successor—which clarifies intent 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?

  States a specific action—retire an already-stored note as superseded after a missed supersedes parameter—and clearly distinguishes it from vectr_revoke, whose purpose is for actually false notes. The description also ties to the tool's title phrase 'post-hoc' and names the note-identification convention from vectr_recall.

  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 tells the agent when to use this tool (after writing a replacement without supersedes), when not to use it (use vectr_revoke when the note is actually false), and how to handle the superseded_by parameter, including omitting it when there is no successor. It also notes reversibility with vectr_reinstate.

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

• vectr_unanchorA
  4.9/5.0
  Behavior5/5

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

  Beyond the idempotentHint annotation, the description explains exactly what idempotency means here: never-anchored paths are reported back, not treated as failures. It also discloses the exact-string comparison contract and the effect on staleness checks, adding substantial behavioral detail beyond the annotation flags.

  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?

  Every sentence earns its place: core action, inverse relationship, use cases, idempotency semantics, and comparison behavior. The most identifying information is front-loaded, and the phrasing is dense without being bloated.

  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 two-parameter mutation tool with no output schema, the description covers all operational aspects an agent needs: what it does, when to use it, what to expect from idempotency, and how path matching works. Nothing essential is missing.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3, but the description adds meaning beyond the schema: anchors are workspace-relative paths, comparison is exact-string on the spelling used at anchor time, and note_id refers to an existing note from vectr_recall. This extra context helps the agent construct correct arguments without opening 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 names a specific verb ('Remove'), a specific resource (file paths from an existing note's anchor set), and identifies the operation codename (UPG-ANCHOR-DETACH). It explicitly positions itself as the inverse of vectr_anchor, making sibling differentiation immediate and 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 gives concrete when-to-use conditions: discovering a note was anchored to the wrong file, or when the anchored file's relevance has gone away. It also clarifies what the operation does not mean (never a claim the note is wrong), which prevents misuse in unrelated correction scenarios.

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

• vectr_forgetA
  5/5.0
  Behavior5/5

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

  Annotations already indicate destructiveHint=true, but the description adds critical details: snapshots are preserved (only active notes removed), the all=true option is irreversible, and no-arg call does nothing. No contradictions with 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 concise at four sentences, each serving a distinct purpose: overall function, note_id usage, all=true usage, and edge cases (no args, snapshots). It is front-loaded with the purpose and efficiently structured.

  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 no output schema, the description fully covers behavior for both parameters, the no-argument case, and side effects (snapshot preservation). It references a sibling tool for IDs, making it self-contained and complete for correct 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?

  Schema descriptions are 100% covered, but the description adds practical meaning: note_id is the [#N] from vectr_recall, and all=true is irreversible. This helps the agent understand the context and consequences of each parameter 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 deletes working-memory notes. It distinguishes between deleting one note by ID (the usual case) and deleting all notes (for refactoring). It references the sibling tool vectr_recall for note IDs, making the purpose specific and 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?

  Explicit guidance is provided: use note_id for stale or superseded notes, use all=true after a large refactor, and calling with no arguments deletes nothing. This helps the agent decide when and how to invoke the tool, distinguishing it from other memory tools like vectr_recall or vectr_remember.

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

• vectr_map_saveA
  5/5.0
  Behavior5/5

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

  Annotations indicate idempotentHint=true and destructiveHint=false. The description aligns, stating the call is a no-op if a passport already exists. It also adds details like token length guidelines and that overwrite=true replaces the existing summary.

  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 (~4 sentences) and front-loaded with purpose and conditions. Every sentence adds value without redundancy.

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

  Completeness5/5

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

  Given the tool's simplicity (2 params, no output schema), the description covers all essential aspects: when to use, what to write, behavior on existing passport, and overwrite option. No gaps remain.

  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?

  Beyond schema descriptions, the description adds critical guidance: what to write in the summary (codebase purpose, tech stack, modules, etc.) and a token range (200-350). This significantly helps the agent craft the correct input.

  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: saving a synthesized codebase summary as a permanent passport. It distinguishes this from siblings by specifying it should be called only after vectr_map returns raw metadata, not when a saved summary already exists.

  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 conditions: 'Call this ONLY after vectr_map returned raw metadata — i.e. on your first visit to a codebase. NOT when vectr_map already returned a saved summary.' Also explains no-op behavior and the overwrite parameter.

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