Server Quality Checklist

Tool Scores

• rememberA
  4.3/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full transparency burden. It does well: refusal conditions are spelled out, 'nothing is written on a refusal' is stated, replica queuing is disclosed, and the reply shape is described. It could go further on permissions or side effects, but the core behavior is unusually 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?

  One dense paragraph, but each sentence earns its place: purpose, pre-call lookup, life-item exclusion, replica behavior, refusal guarantees, check semantics, and response shape. The core purpose is front-loaded, and there is 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 a complex 17-parameter tool with no output schema, the description supplies the missing operational context: when to call it, when not to, what happens on a replica, refusal behavior, and what the reply will contain. It deliberately delegates itemized check-kind details to server instructions, which is reasonable alongside a heavily documented schema.

  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 94%, so the schema already documents the parameters thoroughly. The description adds only a high-level note about check_kind/check_path/check_literal(s) being an optional machine-runnable proof and points to server instructions, which is helpful but not essential 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 opens with a precise verb and resource: 'declares a NEW item (Rule, Orientation, Report, Lookup or Chunk) through the write gate.' It immediately distinguishes itself from siblings by saying lookup is for correcting existing items and shelve is for the owner's life, so an agent can tell what this tool is for.

  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 routing guidance is given: 'Call lookup first' to avoid near-duplicates, and 'for anything about the owner's own life use shelve, never this.' It also tells the agent what to expect on a replica ('queued for the main machine' is not an error), which is a useful when-to-use signal.

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

• markA
  4.4/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden, and it is thorough: it explains default behavior, verdict precedence, noise semantics, retirement from injection surfaces, replica queueing, refusal conditions, and the response contents.

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

  Conciseness5/5

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

  The description is dense but every sentence contributes necessary behavioral information. It is front-loaded with the core purpose and proceeds logically through default behavior, alternative behavior, replica handling, refusals, and reply format.

  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 no output schema and no annotations, the description is remarkably complete. It covers expected inputs, edge cases, failure modes, asynchronous behavior, and the response the agent will receive, leaving no material ambiguity.

  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 schema already documents both parameters. The description adds value beyond the schema by explaining the default verdict, the meaning of noise:true, and the real-world consequences of repeated noise marks.

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

  Purpose4/5

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

  The description clearly states the tool's function: judging an item by recording a verdict (helped or noise). It distinguishes itself from mere lookup or history tools, though it does not explicitly compare itself to any sibling tool.

  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 clearly indicates when to use the tool: for items you were served or looked up. It also explains when the tool is refused (for non-live items). It does not explicitly discuss alternatives among sibling tools, so it stops 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.

• where_usedA
  4.4/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. It discloses that resolution is by bare name only, that unrelated same-name symbols are grouped together, and that results include the indexed commit and whether checkout has moved on. It lacks explicit statements about permissions or rate limits, but given this is a read-only query tool, the behavioral disclosure is strong.

  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 but information-dense. Every sentence earns its place: purpose, usage timing, alternative, read-only nature, important caveat, and expected reply format. It is front-loaded with the primary question and blast-radius framing, making it easy to scan.

  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 tells the agent what it will get (every definition and use site as file:line, indexed commit, checkout state) and what caveats apply. It doesn't explicitly document the 'limit' parameter's effect on output, but the schema already describes that. Without an output schema, mentioning the reply shape is valuable. Minor gap: no statement about performance or large result handling beyond the limit default.

  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 adds useful semantic context about 'bare symbol name' and matching behavior, but does not add much beyond the schema's parameter descriptions. It clarifies the meaning of 'name' well enough, so a 3 is fair.

  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 operation (finding definitions and uses of a symbol name) and clearly distinguishes this from the sibling 'outline', which is about file-level declarations. The verb 'answers who defines and who uses' and the explicit 'code lane' qualifier make the purpose unmistakable.

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

  Usage Guidelines5/5

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

  The description gives explicit guidance on when to use this tool: 'the question to ask before changing a function, struct or variable'. It also names the alternative, 'Use outline instead to see everything one file declares', and warns about the blast radius interpretation. It even advises opening files rather than treating the result list as a conclusion.

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

• libraryA
  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, and it does so thoroughly. It explicitly states 'Read-only', that nothing here is 'ever injected, ranked against a rule, or counted toward any cap', and discloses the search fallback behavior: a search never answers 'nothing' but returns the shelf or shelf list instead. It also states what replies generally look like ('the requested listing or entry, or that fallback').

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

  Conciseness4/5

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

  The description is moderately concise and front-loaded with the primary purpose, then moves through invocation modes and behavioral caveats. Every sentence contributes useful information, though phrases like 'since the words asked with are rarely the words written' are explanatory but could be trimmed. Overall it is efficient for a tool with four optional parameters and no annotations.

  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 lack of annotations and output schema, the description does a good job covering all call modes, the read-only safety profile, the fallback search behavior, and the write alternative. It does not specify exact response JSON structure or error/edge-case handling, but the four invocation modes and their replies are described well enough for an agent to select and call the tool correctly.

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

  Parameters4/5

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

  Schema description coverage is 100%, so the baseline is 3, and the schema already documents each parameter individually. The description adds value beyond the schema by explaining the no-arguments mode, how label narrows a shelf, how query can be scoped 'within shelf', and how parameters combine to produce different listings. This lifts it above baseline.

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

  Purpose5/5

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

  The description opens with a clear verb and resource: 'reads the owner's everyday knowledge' in the 'Library lane', and enumerates concrete examples like recipes, books, and expenses. It explicitly distinguishes itself from the code lane and from the sibling shelve tool ('Use shelve to write instead'). The multiple invocation modes (no args, shelf, id, query) are all tied to a clear read-only purpose.

  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 provides explicit routing: use shelve for writes, and use this tool for reading everyday knowledge kept apart from the code lane. It also explains which call shape to use for which result ('No arguments lists the shelves...', 'shelf lists that shelf's entries', 'id returns one entry whole', 'query searches'). It does not exhaustively distinguish from other read siblings like lookup or get, but the lane separation and mode-by-mode guidance are strong.

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

• resolveA
  4.5/5.0
  Behavior5/5

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

  With no annotations, the description carries the full behavioral burden and does so thoroughly: it discloses replica queuing ('queued for the main machine' is not an error), rechecking under the write lock causing loud failure, and the exact success/refusal reply text.

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

  Conciseness5/5

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

  The description is dense but every sentence carries operational information: purpose, preconditions, replica behavior, concurrency, and response format. It is front-loaded with the core purpose and then covers failure modes.

  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 mutable, concurrency-sensitive tool with no output schema and no annotations, the description covers prerequisites, failure semantics, replica behavior, and return text. An agent has enough to select and invoke it correctly.

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

  Parameters3/5

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

  Schema coverage is 100%, so the schema already documents id, keep, and discard. The description operationalizes keep as 'surviving revision hash' and discard as 'every other current head', but this mostly restates the schema, with no additional parameter format or value constraints.

  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 and resource: 'settles an item with more than one current head' and ties it to the exact state 'what get reports as DIVERGED'. This clearly distinguishes it from sibling tools like get, which reports divergence, and revise, which creates divergent versions.

  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 an explicit trigger condition ('what get reports as DIVERGED') and instructs the agent to 'Read history first; never guess which head is real'. It does not explicitly enumerate alternatives or when-not-to-use conditions, so it falls just 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.

• unpinA
  4.6/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden. It discloses idempotency, replica queueing behavior, the refusal condition, and the possible reply strings. This is exceptional behavioral transparency for a mutating tool.

  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 but every sentence conveys necessary information: purpose, alternative, edge cases, and response semantics. Slightly long and the 'Code lane:' opener is opaque, but otherwise well-structured and front-loaded.

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

  Completeness5/5

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

  For a one-parameter tool with no output schema and meaningful edge cases, the description covers operation semantics, alternatives, idempotency, replica behavior, refusal conditions, and expected replies. Nothing essential to invoking it correctly is missing.

  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 the schema already documents the sole 'id' parameter as 'The id to unpin (remove the Always binding from it)'. The description adds context like 'existing item' and idempotency, but does not substantially enhance the parameter's meaning beyond the schema baseline.

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

  Purpose5/5

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

  States a specific verb ('removes') and resource ('the Always binding from an existing item'), and explicitly distinguishes itself from revise. This gives an agent a clear, differentiated understanding of the operation.

  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 to use revise when anything besides the binding needs to change, and explains when unpin is refused. This provides concrete selection criteria and a conditional path for using it correctly.

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

• historyA
  4.7/5.0
  Behavior5/5

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

  With no annotations, the description carries the full behavioral burden and does so thoroughly: 'Read-only; nothing is ever deleted from the log' explains durability and safety. It also discloses the unknown-id response ('no history for id X' is 'not an error') and the one-line-per-revision reply format.

  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: primary action, sibling alternative, behavioral guarantees, and output format. It is front-loaded with the core verb and resource, then strategically narrows scope and edge cases without any 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?

  There is no output schema, so the description's explicit mention of reply format ('one line per revision') and unknown-id handling fills the gap. It also covers retraction semantics and a pre-revision/retraction use case, making it complete for an agent to invoke safely and 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%, and the schema's description of id ('The id whose whole life to walk') already conveys meaning. The tool description reinforces the id's role but adds no new syntactic or format detail beyond that, so the baseline of 3 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?

  Description states a specific verb and resource: 'walks one item's whole life by id, oldest first' and lists what is included (declare, revise, retraction with sequence number, revision hash, author). It also distinguishes from sibling get: 'Use get instead for only the current version.'

  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 alternative guidance: 'Use get instead for only the current version.' Also gives a concrete precondition: 'read it before you revise or retract again.' This clearly tells the agent when to choose history over get and when the history is still meaningful.

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

• lookupA
  4.7/5.0
  Behavior4/5

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

  No annotations are provided, so the description carries the full burden. It discloses read-only behavior ('Read-only'), non-interactivity ('nothing here reaches you unprompted'), matching limits ('up to 25 matching lines'), and the shape of replies ('id, kind, text' plus counts). It doesn't explicitly discuss rate limits or failure modes, but the behavioral surface is unusually well disclosed for a search tool.

  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 but purposeful; nearly every clause earns its place and the critical scoping constraint and call-before-remember advice are front-loaded. It is a long paragraph, but the complexity of five invocation modes justifies the length. It could be slightly tightened, but there is 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 output schema, the description covers what an agent needs: return shapes (catalogue, matches with id/kind/text, 'no matches'), limits, scope semantics, and exclusions (Lookup items are not queryable by free-text). The sibling context and missing output schema are fully compensated by the description's detail.

  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 already 100%, but the description adds semantic interactions beyond the schema: 'key answers only a Lookup item's own exact key (query and scope are then ignored)' clarifies precedence, and the mode-by-mode breakdown (no args, scope alone, scope+query, query alone) explains what combination produces what result. This is meaningful added value over the schema alone.

  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 strong verb-resource pair ('searches THOR's memory') and immediately distinguishes itself from a current-project-scoped search. It names the sibling 'search_code' implicitly by contrast ('never scoped to only the current project') and covers all invocation modes, so an agent knows exactly what this tool does.

  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 'Call this before remember, so an existing near-duplicate becomes a revise instead,' which gives a concrete when-to-use instruction and a direct alternative ('remember', 'revise'). It also enumerates the parameter-mode conditions (no arguments, scope alone, scope+query, query alone, key alone), leaving no ambiguity about which input combination to choose.

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

• outlineA
  4.7/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries the full behavioral disclosure burden. It does this well by stating read-only status, explaining the important distinction between 'not indexed' and 'defines nothing,' and specifying the exact response format: one line per definition with name and line number.

  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: purpose, alternative tool, parameter requirement, read-only flag, edge-case behavior, and output format. The purpose is front-loaded, and the length is justified because there are no annotations to offload behavioral information to.

  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 one-parameter, read-only tool with no output schema, this description is complete. It covers how to invoke the tool, what it returns, how to interpret the two plain-text outcomes, and which sibling to use for a different need. No critical operational detail is missing.

  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 the schema already documents the single path parameter as 'Repository-relative path, exactly as the index stores it.' The description only repeats the repository-relative aspect without adding new syntax, validation, or format details, so 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 a specific action: it lists what one file declares in line order, giving the file's shape without reading the whole file. It also explicitly distinguishes itself from the where_used sibling, so an agent can tell them apart immediately.

  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 routing guidance: 'Use where_used instead to find every caller of one symbol.' This tells the agent when not to use outline and which sibling to choose instead. The intended use case—inspecting a file's declared shape—is clear from the first sentence.

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

• pinA
  4.7/5.0
  Behavior5/5

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

  With no annotations provided, the description fully carries the behavioral burden. It discloses idempotency, replica queueing behavior, refusal conditions for items that cannot carry a binding, and the possible reply strings. This is unusually complete for a tool description.

  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 in the description carries a distinct, useful behavioral fact. It is dense but not bloated, and the most important purpose is front-loaded before edge cases and alternatives.

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

  Completeness5/5

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

  The description is complete for a tool with no output schema and no annotations. It covers the normal success outcome, the no-op case, replica behavior, refusal cases, and the alternative tool, leaving little for an agent to guess.

  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 covers the only parameter id with 100% coverage and a clear description. The tool description reinforces that the item is existing, but does not need to add more because the schema handles parameter semantics 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 states a specific action: adds the Always binding to an existing item, and clarifies the effect ('served in full at every session start'). It also distinguishes the tool from revise by name, so an agent can tell what pin does without inferring from the name alone.

  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 to use revise instead when anything besides the binding needs to change, which gives clear routing between sibling tools. It also covers the already-pinned case, replica behavior, and refusal cases, so an agent knows when the operation will not behave as a normal write.

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

• retractA
  4.7/5.0
  Behavior5/5

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

  With no annotations at all, the description carries full weight and does so thoroughly. It discloses the non-destructive nature ('nothing is deleted, and history still walks it'), replica queueing behavior, the required non-blank reason, the exact reply format, and the tombstone rule. Nothing about the operation's side effects is hidden.

  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 carries distinct information: purpose, scope, alternative, constraint, replica behavior, future recovery, and reply format. Despite density, it is well-organized and front-loaded with the core semantics before the edge cases. There is no filler or repetition.

  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 subtle semantics (tombstone, live-everywhere removal, replica queueing), and the description addresses all of them. It also covers the required reason, refusal behavior, response format, and post-retraction workflow. With no output schema, this level of detail is sufficient 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%, and the description does not add meaning beyond the schema for parameters. It reinforces the reason requirement and the refusal of blank reasons, but those are already stated in the schema's property description. Baseline 3 is appropriate since the schema already documents 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 states a specific verb and resource: 'removes an item that is simply WRONG or no longer applies', and immediately distinguishes it from the sibling 'revise'. It also clarifies the nuanced effect (stops being live everywhere, but nothing is deleted), so an agent can tell exactly what retract does versus other mutations.

  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 names the alternative: 'Use revise instead when the item merely changed', giving a clear decision rule. It also explains what to do after retraction ('Bringing the fact back later is a fresh remember, never a revise of the tombstone'), and covers replica behavior without treating it as an error. This is complete routing guidance.

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

• search_codeA
  4.7/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 behavioral burden and does so well. It discloses read-only behavior, that results name the commit read, warns that the working copy may have moved on, advises opening the real file before trusting line numbers, and states the tool plainly reports when no code index is configured rather than returning empty results.

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

  Conciseness5/5

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

  The description is dense but every sentence earns its place: purpose, sibling routing, safety, staleness warning, error behavior, and output format are all covered without repetition. It is front-loaded with the core purpose and uses sentence-level structure that is easy for an agent to parse.

  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?

  There is no output schema, so the description correctly explains the return format: up to 10 snippets as path:start-end plus text, with commit context. It also covers the no-index case and the staleness caveat. For a two-parameter search tool, the description is complete enough for an agent to select and invoke it correctly.

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

  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 both parameters. The description adds little beyond what the schema says: it mentions case-insensitive substring matching and a 10-snippet output default, but these largely mirror the schema's own descriptions. Baseline 3 is appropriate since the schema does 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 names a specific verb and resource: searches the indexed SOURCE CODE of the current project, not memory. It further clarifies the search is case-insensitive substring matching. It distinguishes itself from lookup and where_used, making sibling differentiation clear.

  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 lookup instead for facts stored in memory, and where_used instead for a symbol's callers. This gives direct routing guidance among siblings with no ambiguity about when this tool is the right choice.

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

• shelveA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full behavioral burden and does so thoroughly. It discloses replica queueing behavior, exact success replies ('filed <id>' / 'revised <id>'), refusal categories (no fitting shelf, near-duplicate, over-length body), and the one_thing_because requirement. This is far beyond the minimum for a write operation and gives the agent accurate expectations for side effects and 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 a single dense paragraph, but every sentence carries useful information and the main operation is front-loaded. Some semicolon-heavy refusal clauses could be more readable, but there is no filler or redundant restating of the schema. It earns its length through behavioral and routing detail.

  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 6-parameter write tool with no output schema and no annotations, the description is remarkably complete. It explains input requirements, output strings, refusal behavior, queue behavior, and the alternative tool. The rich schema fills in the remaining parameter-level details, so an agent has everything needed to select and invoke the tool correctly.

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

  Parameters4/5

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

  The input schema already has 100% description coverage, so the baseline is 3. The description adds important semantic constraints beyond the schema, such as the ~600-character threshold for one_thing_because and the fact that id means correction rather than new filing. It does not restate every parameter, but the schema handles those details; the description enhances the most decision-critical semantics.

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

  Purpose5/5

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

  The description states a specific action and resource: it "files one new entry on an EXISTING shelf, or corrects one by id." It also actively distinguishes itself from the code lane and from the remember sibling, so an agent can tell which lane this belongs to. The core operation is unambiguous and not a tautology of the tool name.

  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 routing guidance: "Use remember instead for facts about code or how to work, never for the owner's own life." It also states what shelve cannot do (create a shelf) and instructs the agent to ask the owner when no existing shelf fits. This is clear when-and-when-not guidance with a named alternative.

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

• statusA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description carries full responsibility. It discloses that the tool is read-only, takes no arguments, returns one count per line, and lists the exact count categories. This gives the agent an accurate behavioral model.

  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 core purpose and then enumerates the specific counts. It is slightly dense with enumerated categories, but every clause adds useful behavioral or selection information.

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

  Completeness5/5

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

  For a zero-parameter, read-only status tool with no output schema, the description fully covers what the tool does, what it returns, and how it differs from nearby siblings. No critical gap remains.

  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?

  There are zero parameters, which is the baseline-4 case. The description reinforces this by saying 'takes no arguments,' so there is no ambiguity left.

  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 and resource: 'reports what the memory holds right now' via live counts across specified categories. It clearly differentiates itself from get/history by noting those are for one specific item.

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

  Usage Guidelines5/5

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

  Explicitly states when to use this tool versus alternatives: 'Use get or history instead for one specific item.' This gives an agent a clear routing decision without needing to open sibling schemas.

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

• getA
  4.9/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden, and it fully delivers: it declares the tool read-only, promises a plain honest error rather than a blank success-like reply, enumerates the exact error conditions, and describes the two possible outputs. This is exemplary transparency for a simple read operation.

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

  Conciseness5/5

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

  The description is compact yet dense: purpose, sibling guidance, read-only guarantee, error behavior, and return format are all covered in about five sentences. It is front-loaded with the most important information and contains no filler.

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

  Completeness5/5

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

  For a single-parameter read-only tool with no output schema and no annotations, this description is fully complete. It tells the agent what the tool does, when to use it (and when not to), what errors look like, and what the response will be. Nothing needed for correct invocation 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?

  The schema already covers 'id' at 100%, but the description adds meaningful semantics: the id must already be known, an unknown id produces an honest error instead of a blank result, and the reply is the whole item. This goes beyond the schema's 'The id to show' by clarifying the contract and failure behavior.

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

  Purpose5/5

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

  The description opens with a specific verb and resource ('shows one item whole, by id') and immediately distinguishes itself from the sibling 'lookup', which is for when the id is not known. This gives an agent a crisp mental model of the tool without needing to inspect the schema.

  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 to use 'lookup' when the id is not already known, and for DIVERGED items it tells the agent to read history and then use 'resolve'. These are concrete routing instructions that select this tool versus the relevant alternatives.

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

• reviseA
  4.9/5.0
  Behavior5/5

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

  No annotations are provided, so the description carries the full burden, and it delivers: it discloses the write-gate mutation path, the omit-keeps/empty-clears merge semantics, the replica queueing behavior, the refusal grounds (including the unnamed-field-drop rule), and the reply format (revised id and event sequence, or refusal text). This is exceptional disclosure for an unannotated write tool.

  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 tightly structured: purpose first, then the core merge rule, then the replica caveat, then usage preference, then refusals and reply. Roughly 120 words cover a 19-parameter tool's essential contract with zero filler; 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?

  Despite high complexity (19 params) and no annotations or output schema, the description covers the full operational contract: what it does, the merge/clear model, replica behavior, refusal conditions, and the response shape. The schema covers all parameter details at 100%, so nothing an agent needs to invoke it correctly is left unaddressed.

  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 earns one extra point by synthesizing the cross-cutting convention — 'a field left unmentioned keeps its current value, and none may silently vanish' — which unifies the per-parameter omit/clear semantics that the schema spells out individually. It adds a conceptual frame the schema alone does not provide.

  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 opening states a specific verb and resource: 'corrects an EXISTING item by id,' which immediately distinguishes revise from create-oriented siblings like remember. It also explicitly contrasts itself ('Prefer this over remember for anything that already exists and merely changed'), so an agent can select it without inspecting the schema.

  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 routing advice: 'Prefer this over remember for anything that already exists and merely changed.' It also tells the agent when behavior differs ('On a replica this queues instead of writing') and how to interpret the non-error response. This is clear when-to-use guidance with a named alternative.

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