Server Quality Checklist

Tool Scores

• swg_readA
  3.7/5.0
  Behavior1/5

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

  The description claims a read-only operation, but annotations have readOnlyHint: false, indicating the tool may modify state. This is a direct contradiction, so score is reduced to 1 per rules.

  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 well-structured with the main purpose first, then key details about return values, INVALID handling, and limitations. Each sentence adds value without unnecessary fluff, though it could be slightly more compact.

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

  Completeness4/5

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

  Given the tool's simplicity (1 param, no output schema), the description covers essential aspects: return format, version usage, INVALID recovery, and limitations. It lacks explicit path format details but is otherwise complete for an agent to use 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 only parameter 'path' has no schema description (0% coverage). The description adds minimal context: it is a 'workspace text file path'. While sufficient for basic understanding, it lacks details like allowed formats or 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 clearly states the action ('Read') and the resource ('a workspace text file under coherence tracking'). It distinguishes from siblings by mentioning the version return for swg_write_cas and the need for swg_reacquire when in INVALID state.

  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 usage context: it's for reading files under coherence tracking with version info for CAS. It also states when not to use it (SINGLE-HOST only, not for network mounts or multi-host scenarios) and points to swg_reacquire for recovery from INVALID state.

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

• swg_statusA
  4.1/5.0
  Behavior5/5

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

  The description goes beyond the readOnlyHint annotation by detailing the specific states reported (coordinator on/off/unknown, per-path enforced/not_registered, etc.) and explicitly lists limitations (e.g., 'Out of guarantee and NOT detected in v1: ...'). 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.

  Conciseness3/5

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

  The description is dense and contains many technical details (fields, limitations). While front-loaded with 'Report coherence state', it could be more concise. The structure is somewhat fragmented with commas and semicolons.

  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?

  With no output schema, the description fully explains the return values (coordination state, per-path status, attachment/degradation, session ID, etc.) and covers limitations. It is sufficiently complete for the tool's purpose.

  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, and schema coverage is 100%. Baseline for no parameters is 4. The description does not add parameter semantics but explains the output, which is not directly relevant to this dimension.

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

  Purpose5/5

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

  The description starts with 'Report coherence state', a clear verb+resource combination. It lists specific fields and constraints, and it is distinct from sibling tools like swg_read, swg_write, etc., which have different purposes.

  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?

  The description does not explicitly state when to use this tool versus alternatives. It mentions 'SINGLE-HOST only' as a constraint but does not provide when-to-use or when-not-to-use guidance relative to sibling tools.

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

• swg_reacquireA
  4.3/5.0
  Behavior5/5

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

  Beyond the readOnlyHint=false annotation, the description explains re-minting identity, version lineage enforcement, and lists out-of-guarantee scenarios. This adds significant behavioral context.

  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 sentence with additional clarifications. It conveys essentials without excess, though it could be slightly more structured for readability.

  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 niche purpose, the description covers recovery action, behavioral rules, and reliability caveats. It is sufficient for an AI agent to use correctly.

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

  Parameters1/5

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

  The schema has one required parameter 'path' with no description. The tool description does not explain what 'path' represents, leaving ambiguity. With 0% schema coverage, the description should compensate but fails to.

  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 recovers from stale_view deny by re-minting identity and returning current bytes. It distinguishes itself from siblings like swg_read and swg_write by specifying the recovery 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?

  Provides explicit when-to-use ('recover from stale_view deny') and when-not-to-use (SINGLE-HOST only, not for divergent history). Also gives instructions to write FROM exact bytes returned, with warnings about limitations.

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

• swg_write_casA
  4.5/5.0
  Behavior5/5

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

  The description transparently discloses the tool's behavior: it rejects stale writes with a typed conflict (version_mismatch) and returns current_version, it does not auto-merge, and it has retry logic bounded by a per-session counter but not livelock-proof. It also documents critical limitations: single-host only, undetected issues for multi-host or network mounts. Annotations only indicate non-read-only (readOnlyHint=false), so the description provides extensive additional behavioral context.

  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 relatively long but well-structured: it starts with the core purpose, then explains the usage flow, conflict handling, and limitations. Every sentence provides useful information, but could be slightly condensed without losing clarity. The front-loading is effective.

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

  Completeness4/5

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

  Given the tool's complexity (CAS, conflict resolution, single-host constraint), the description covers most essential aspects: how to use, conflict response, retry guidance, and limitations. It lacks explicit return value documentation (no output schema), but implies the conflict response includes current_version. The distinction from siblings is clear.

  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 0% schema description coverage, the description must compensate. It explains that 'expected_version' comes from swg_read (not swg_reacquire) and 'new_content' is the merged result. 'path' is not elaborated, but its purpose is clear from the schema. The description adds meaningful context for two of three parameters, enhancing understanding beyond the bare 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 identifies the tool as a compare-and-set write operation for concurrent same-key updates. It explains the CAS pattern (read, merge, write with expected_version) and distinguishes from swg_write (non-CAS) and swg_reacquire (recovery only). The verb 'write' and resource 'shared file' with CAS semantics 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 Guidelines4/5

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

  The description explicitly states when to use the tool (after reading and merging) and how to handle conflicts (re-read, re-merge, retry). It warns that swg_reacquire should not be used to get the version for CAS. It also notes the single-host limitation and the cooperative agent assumption. However, it does not explicitly list alternative tools for different scenarios, though siblings are given.

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

• swg_writeA
  4.6/5.0
  Behavior5/5

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

  Annotations indicate readOnlyHint=false, so no contradiction. Description details stale view detection, preemption, single-host limitation, and v1 limitations. Adds significant behavioral 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.

  Conciseness4/5

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

  Lengthy but efficient; every sentence adds value. Front-loaded with core action, then details. Not overly verbose given complexity.

  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 error conditions, recovery procedures, limitations (single-host, no auto-merge). No output schema, but return values are implicitly clear from context. No gaps for agent 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 0%, requiring description to compensate. Description implies 'path' and 'content' via 'file' and 'bytes', but does not explicitly describe them. Since parameters are simple and purpose is clear, minimal but adequate.

  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 'Write a workspace text file' with specific workflow (acquire->write->commit). Distinguishes from siblings like swg_write_cas and mentions recovery 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?

  Explicitly says when to use (after acquire, before commit), when not (stale view, preempted), and recovery steps with alternative tools (swg_reacquire, reacquire_and_reconcile).

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