Server Quality Checklist

Tool Scores

• session_treeB
  3.3/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. 'Show' implies a read-only operation, and the description provides useful context about output scope (all sessions, relationships, status). However, it does not explicitly state that it is read-only, nor disclose potential caveats like performance on large trees or exact output 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?

  The description is compact and impactful, using two clear sentences and a powerful analogy. Every sentence earns its place; the analogy gives immediate mental model without extra wording.

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

  Completeness3/5

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

  For a simple read-only tool with one parameter, the description conveys the core purpose and what is shown. However, with no output schema, it leaves the exact return format unspecified, and it does not discuss output ordering, size limits, or whether the tree is textual or graphical. The description is adequate but not rich.

  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 describes project_root with full coverage. The description adds no parameter-specific detail beyond mapping 'this project' to project_root, so it does not meaningfully compensate for or extend the schema.

  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 specifies the action ('Show') and resource ('full session tree'), and adds useful detail about what is shown: all sessions, their relationships, and status. The git log --graph analogy helps convey the tree/graph nature, though it does not explicitly differentiate from sibling tools like session_status or session_diagram.

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

  Usage Guidelines2/5

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

  No guidance is given about when to use this tool instead of siblings such as session_status, session_log, or session_diagram. The description implies it is for viewing the whole graph, but it does not state exclusions or alternatives, so an agent must infer the appropriate context.

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

• session_diagramB
  3.4/5.0
  Behavior3/5

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

  No annotations are provided, so the description bears the full disclosure burden. It does add genuinely useful behavioral context: the tool auto-scans project files to build the dependency graph, and the output must be 'passed to a Mermaid renderer to visualize' (i.e., the tool does not render itself). However, it does not disclose whether `regenerate` is destructive, whether sessions cache diagrams, or any side effects from the auto-scan — gaps that matter for a mutation-ish tool with zero annotation coverage.

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

  Conciseness4/5

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

  Three tight sentences, each earning its place: the main purpose is front-loaded, the auto-scan behavior follows, and the renderer hand-off closes. No filler or redundancy. It loses one point only because the session-based behavior implied by `session_id` is never mentioned, leaving a small completeness gap in an otherwise efficient structure.

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

  Completeness3/5

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

  For a tool with 3 params, no output schema, and no annotations, the description is serviceable but incomplete. It explains the auto-scan and Mermaid output but never mentions the session dimension that `session_id` depends on, gives no return-format detail (Mermaid string length, cache behavior), and leaves the required `project_root`'s role only loosely implied. What is needed to call the tool correctly is mostly covered; the session semantics and output expectations are not.

  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 67%: `regenerate` and `session_id` are already well-documented in the schema, leaving the required `project_root` undocumented. The description's 'Auto-scans the project files' gives `project_root` useful context (it is the root scanned to build the graph), which partially compensates. But the description never ties the `session_id`/session-cache concept to the schema, so it adds only marginal value over what the schema already states.

  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?

  Clear verb+resource pairing: 'Show or regenerate the architecture diagram' in 'Mermaid format', with the auto-scan behavior explicitly stated. All sibling tools are session lifecycle operations (init, checkpoint, load, update, status, log) or claims, so the diagram focus is self-evidently distinct even though no sibling is named — unlike a high-5 there's no explicit 'use X instead' comparison, so it stops at 4.

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

  Usage Guidelines3/5

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

  No explicit when-to-use or when-not-to-use guidance, and no alternatives are named. Usage must be inferred from the purpose statement ('Show or regenerate the architecture diagram'). The sibling tools are all session operations so confusion is unlikely, but the description does not actively route the agent — this is implied usage at best, meriting a 3.

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

• session_updateB
  3.4/5.0
  Behavior2/5

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

  There are no annotations, so the description carries the full behavioral disclosure burden. It states that information is added to a session but does not disclose side effects, whether a session must already exist, whether entries are append-only, or what happens on repeated calls. This is only slightly more informative than the tool name itself.

  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 with no filler. The main action is front-loaded, and the list of supported record types is compact yet informative. Every clause earns its place.

  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?

  With 10 parameters, no output schema, and no annotations, the description should provide more guidance about preconditions, session lifecycle, and how this tool relates to session_init, session_checkpoint, and session_log. The description explains high-level intent but leaves an agent uncertain about operational details.

  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 high at 80%, so most parameter meaning is already available. The description adds value by naming the kinds of information that map to the 'type' enum, but it does not explain nuanced parameters like reasoning, risk_level, or context_pct beyond what the schema already says.

  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 identifies a specific action ('Add information') on a specific resource ('current session') and lists the categories of information it records. Clear enough for an agent to understand the core purpose, though it does not explicitly differentiate itself from siblings like session_log.

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

  Usage Guidelines4/5

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

  The description gives clear timing guidance ('Use this throughout the session') and enumerates valid content types. It does not state when not to use this tool or contrast with alternatives such as session_checkpoint or session_log, which keeps it from a 5.

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

• session_statusA
  3.5/5.0
  Behavior3/5

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

  With no annotations, the description carries the behavioral burden, and it does communicate that this is a read-only 'get' operation and names the returned status areas. However, it does not disclose what happens when no session exists, whether the optional context_pct parameter changes the output, or whether any side effects/errors are possible.

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

  Conciseness5/5

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

  The description is a single efficient sentence that front-loads the verb and resource, then enumerates the useful output categories. There is no filler or redundant phrasing.

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

  Completeness3/5

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

  For a simple status retrieval with one optional parameter, naming the output areas is mostly sufficient. However, the description does not connect the optional context_pct parameter to the 'context warning level', and with no output schema or annotations, the agent is missing some context about return shape and error or prerequisite behavior.

  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 baseline is 3 even though the tool description itself never mentions context_pct. The schema says 'Current context% for threshold warning', which gives basic meaning, but the tool description does not clarify how this optional number influences the status ouput.

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

  Purpose5/5

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

  The description clearly states a specific action ('Get'), a defined resource ('current session's status'), and then enumerates exactly what is included: recorded items, dead ends, task progress, and context warning level. This is enough to distinguish it from siblings like session_log or session_load, which operate on session content rather than report an aggregate status.

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

  Usage Guidelines2/5

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

  There is no guidance on when to use this tool versus alternatives such as session_log, session_checkpoint, or session_diagram. The phrase 'Get the current session's status' implies a monitoring use case, but the description never states conditions, prerequisites, or exclusions, so an agent must infer selection.

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

• session_searchA
  3.8/5.0
  Behavior3/5

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

  There are no annotations, so the description carries the burden. It discloses that the search spans ALL sessions and implies semantic, memory-style queries. However, it does not mention result format, pagination, performance characteristics, or whether this is strictly read-only beyond the word 'Search.'

  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 short, front-loaded with the core action, and every sentence earns its place. The examples are compact and materially improve understanding without adding noise.

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

  Completeness3/5

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

  The description gives clear purpose and realistic usage examples, making it minimally viable for an agent to invoke. However, with no output schema and no annotations, the missing details about return values, handling of empty results, and the relationship between project_root and the 'ALL sessions' scope leave notable gaps.

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

  Parameters2/5

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

  Schema description coverage is 0%, and the description does not explain type_filter or project_root. The example questions hint at query content and possibly filters like error or dead_end, but the agent must infer how project_root relates to 'ALL sessions' and when to use type_filter. The description does not adequately compensate for the lack of schema descriptions.

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

  Purpose5/5

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

  The description states a specific verb and resource: 'Search across ALL sessions for a query.' It also distinguishes itself from session-management siblings by emphasizing the global, cross-session scope, and the concrete example questions clarify exactly what kind of tool this is.

  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 'Useful for' examples give strong, concrete guidance on when to call this tool, such as recalling decisions, errors, file edits, and dead ends. It does not explicitly say when not to use it or name alternatives, but the context is clear enough for an agent to select it appropriately.

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

• session_initA
  3.9/5.0
  Behavior3/5

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

  No annotations are provided, so the description carries the behavioral burden. It discloses a new session is created, that it supports tree structure via parent_session_id, and that it is intended as the start of a session. However, it does not reveal the return value (likely a session ID), whether it persists state, or what happens if a session already exists.

  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 short sentences, with the core action and timing front-loaded. Every sentence adds useful context and there is no redundancy or filler.

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

  Completeness3/5

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

  The description adequately covers why, when, and with what parameters to call the tool. But with no output schema and no annotations, it should also tell the agent what the tool returns (e.g. a session ID to use with sibling tools) — that is missing, leaving the definition short of complete.

  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 baseline is 3 even without extra parameter detail. The description adds only light rephrasing — 'current project' for project_root and 'continue from a previous session (tree structure)' for parent_session_id — without adding new constraints or formats.

  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 (Initialize), resource (CogSession), and scope (current project). The word 'new' and phrase 't the START' clearly separate this from siblings like sesssion_load, sesssion_update, and sesssion_checkpoint.

  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?

  Explicitly says to call this at the START of a Claude Code session, which gives a clear invocation context. It also explains when to provide parent_session_id (continue from previous session) and focus (session topic), though it does not name alternative tools for non-start cases.

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

• session_loadA
  4/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden. It discloses that this is a load/retrieval action, returns a handoff brief of roughly 250 tokens, and is intended as the session-start context retrieval mechanism. It does not explicitly state 'read-only' or discuss side effects, but 'load' strongly implies non-mutating behavior and the return-size hint adds useful precision.

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

  Conciseness5/5

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

  The description is two tight sentences with no filler. Key information is front-loaded: the action, the timing, and the expected return size. Every sentence earns its place.

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

  Completeness4/5

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

  For a tool with three parameters, full schema coverage, and no output schema, the description covers the essential operational context: when to call, what it loads, and what the returned content looks like. It could be more explicit about load_level variations, but the schema already handles those.

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

  Parameters3/5

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

  Schema description coverage is 100%, so all three parameters are already documented. The description adds no new parameter-level detail beyond aligning with the default 'handoff' load level via the phrase 'handoff brief,' which is only marginal added value.

  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 states a specific verb and resource: 'Load the handoff from a previous session.' It clearly identifies the tool's core purpose and differentiates it from siblings like session_status or session_search through the 'handoff' and 'new session' framing, though it does not explicitly name an alternative.

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

  Usage Guidelines4/5

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

  The description gives clear timing guidance: 'Call at the START of a new session to get context from the last one.' This tells an agent when to use the tool, but it does not explicitly state when not to use it or compare it with sibling loading/checkpoint tools.

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

• session_checkpointA
  4.2/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly reveals the side effects: it writes several specific files and auto-writes handoff.md to CLAUDE.md so the next session loads it. This gives an agent a solid mental model of what the call does to disk, even without a dedicated effects section.

  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 tight and front-loaded: a one-line purpose, a prominent usage directive, and a compact file list. Every sentence contributes, and the critical 'CALL THIS at 70-80% context' guidance appears near the beginning rather than buried. No wasted words.

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

  Completeness4/5

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

  The description covers the essential call rationale, the exact persistence artifacts, and a key auto-write side effect. A small gap is that it does not state what the tool returns or whether files are overwritten, but the listed outputs and input schema already give enough context for correct invocation.

  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 moderate: one_liner and context_pct are described in the input schema, while trigger has only an enum/default. The description adds a little context-pct meaning via the '70-80% context' guidance, but it does not explain trigger values or elaborate on one_liner usage beyond the schema. It mostly relies on the schema for parameter meaning.

  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 ('Save'), a clear resource ('current session state to disk'), and enumerates the exact files written, making its purpose unmistakable. It also distinguishes itself from sibing tools like session_search or session_status by emphasizing a full persistent dump rather than inspection or incremental update.

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

  Usage Guidelines4/5

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

  The description explicitly tells the agent when to call this: 'CALL THIS at 70-80% context'. This is a concrete trigger condition. It does not, however, contrast this tool with session_update or session_log, so exclusions and alternatives are left implicit.

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

• claim_checkA
  4.3/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden, and it discloses the key behavioral outcome: it reports only failures and remains silent when all claims still hold. This is meaningful beyond the tool name, though it does not mention side effects or permission requirements.

  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 short sentences carry the full purpose, behavior, and result interpretation. The most important information is front-loaded, and 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?

  For a tool with one optional boolean parameter and no output schema, the description is complete: it explains what the tool does, what its output looks like, and how to interpret silence. An agent can call this tool correctly with the information provided.

  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 the single boolean parameter 'all' with 100% coverage, so the description does not need to add much. It provides no extra detail about the parameter beyond what the schema states, which is acceptable given the high schema coverage.

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

  Purpose5/5

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

  The description uses a specific verb ('re-run'), a clear resource ('recorded claims'), and states exactly what it reports (only those that no longer hold). It distinguishes itself from the sibling claim_record by focusing on verification rather than creation.

  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 makes the usage context clear: verifying previously recorded claims by re-running them. It does not explicitly name alternatives or exclusion criteria, but the contrast with claim_record is evident and the behavior is unambiguous enough for an agent to know when to call it.

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

• session_logA
  4.3/5.0
  Behavior4/5

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

  No annotations are present, so the description carries the transparency burden. It discloses ordering, per-line fields, and filtering behavior, and the 'git log' analogy implies a read-only operation. It does not explicitly state the side-effect profile, but nothing about the description suggests mutation.

  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 dense sentences front-load the return format and then add usage guidance. There is no filler, repetition of schema details, or vague phrasing.

  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 optional-parameter log reader with no output schema, the description supplies the necessary return fields, ordering, and a decision rule for filtering. It is complete enough for an agent to invoke it correctly without further 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 clear descriptions for limit, session_id, and type_filter. The description only reinforces 'Filter by type', adding little beyond what the schema already says. Baseline 3 is appropriate when the schema carries the parameter documentation.

  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 the exact resource ('sessions'), the operation mode ('git log'), and the output shape (one line per event, newest first, timestamp, event type, repo state). It is immediately distinguishable from write/status/search siblings by its read-only log framing, even though it does not explicitly name an alternative 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 gives concrete directives: 'Use it to scan history fast, then grep the session's own session.md' and 'Filter by type to answer what has already failed here'. This establishes a clear primary use case and points to a follow-up resource, but it does not explicitly say when to prefer session_search instead.

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

• claim_recordA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries the behavioral burden and does well: it states that claims persist across sessions, are re-checked, and that the proof command must be cheap and read-only so its output can be compared. It does not describe failure modes or notification mechanics, but it discloses the core side-effecting behavior and constraints.

  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 with no filler: the primary action is front-loaded, followed by usage guidance and a key constraint. Nothing repeats the schema verbatim.

  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 tool has five parameters, no annotations, and no output schema, so the description needs to cover purpose, selection context, and behavioral constraints, which it does. It omits explicit return-value and error information, but an agent still has enough to invoke it correctly.

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

  Parameters4/5

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

  Schema coverage is 100%, so the baseline is 3, but the description adds meaningful value by constraining verified_by to be a cheap read-only shell command and explaining how its output is compared. It also grounds asserted_in in durable locations, though expect and watches are left to 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 concrete verb and object: record a claim together with the proving command, and clarifies that the claim will be monitored in later sessions. It clearly differentiates the tool from session management siblings and implies the counterpart relationship with claim_check.

  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 explicitly tells the agent when to use it: for any factual statement written in a durable artifact such as a PR description, code comment, doc, or status report. It does not name alternatives directly or list exclusions, but the sibling context and the 'Use this for' phrasing make the intended scope clear.

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