Server Quality Checklist

Tool Scores

• delete_stateA
  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 explicitly discloses the destructive, irreversible nature of the operation ("permanently") and clarifies that both the key and its associated value are removed. This goes beyond a simple tautology. It does not mention error behavior or return values, which is a minor gap.

  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, clear sentence that fronts the verb and resource, and includes the crucial adverb "permanently." It has no filler or redundancy, making it appropriately sized for the tool's simple purpose.

  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 simple one-parameter delete tool with no output schema, the description covers the core purpose, the destructive effect (key + value), and irreversibility. It does not explain return behavior or what happens if the key does not exist, but these are not critical for a straightforward deletion. Overall, it is sufficiently complete 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.

  Parameters3/5

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

  The input schema already provides 100% coverage with a clear description for the one parameter ("Checkpoint key to delete"). The tool description essentially restates this without adding new details about format, constraints, or special values. A baseline of 3 is appropriate given the complete schema coverage.

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

  Purpose5/5

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

  The description clearly states the action ("Remove"), the resource ("a checkpoint key"), and adds that the value is also permanently deleted. This distinguishes it unambiguously from sibling tools like get_state, set_state, and list_state.

  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?

  The description implies when to use the tool (when you want to delete a checkpoint entry) but provides no explicit guidance on when not to use it or how it differs from alternatives like force_set_state. No prerequisites or edge-case conditions are mentioned.

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

• list_stateA
  4.3/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the return fields (key, version, updated_at), supports pattern matching, and shows default behavior. It does not detail ordering, case sensitivity, or potential side effects, but for a listing operation, this is adequate 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.

  Conciseness5/5

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

  Two concise sentences front-load the purpose and then add essential return-value detail. Every sentence earns its place with 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 one optional parameter, no output schema, and is inherently simple. The description covers purpose, parameter behavior, and return fields completely for the tool's complexity. Sibling tools are named, further enriching 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 coverage is 100%, so the schema already explains pattern, default, and meaning. The description adds the SQL LIKE context and 'omit for all keys', but these are largely redundant with the schema. No additional parameter details are provided, so baseline 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?

  The description uses a specific verb ('List') and resource ('checkpoint keys'), and clarifies matching via SQL LIKE syntax. It distinguishes from siblings like get_state, set_state, and delete_state by clearly indicating enumeration of keys rather than value access or mutation.

  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?

  Provides clear context for the pattern parameter ('Pass '%' or omit for all keys') and implies this tool is for listing keys, not retrieving individual state. However, it does not explicitly state when to use this tool over get_state or other alternatives, so it stops short of full guidance.

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

• force_set_stateA
  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 burden and discloses key traits: 'Unconditionally' indicates no version check, 'Always succeeds' signals reliability. It adds meaningful context beyond the schema, though it could also mention overwriting side effects.

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

  Conciseness5/5

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

  Two compact sentences with no redundancy. The core action is front-loaded, followed by concise usage guidance, making every word earn 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 simple write tool with no output schema, the description covers purpose, behavioral traits, and usage. The 'unconditionally' implication covers overwriting, though explicit mention of potential data loss would make it fully 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 coverage is 100%, so baseline is 3. The description does not add parameter-specific details, but the schema already fully documents key and value, including value format requirement.

  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 'Unconditionally write a checkpoint value,' using a specific verb and resource. It distinguishes from siblings by contrasting with set_state for concurrent writers, making its unique role 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?

  Explicitly states when to use: 'Prefer for single-writer workflows' and when not to: 'For concurrent writers, use set_state with expected_version.' This provides clear alternatives and exclusions.

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

• get_stateA
  4.5/5.0
  Behavior5/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly states the return payload (latest JSON value, version, update timestamp) and the not_found behavior, which fully covers the observable behavior of this read-only 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 two sentences, front-loaded with the core purpose. No wasted words.

  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 is simple (one parameter, read-only). The description explains the return format and the not_found case, which is complete for this operation. An output schema is absent, so the description's return value explanation is sufficient.

  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?

  Input schema has 100% coverage of the single 'key' parameter with an example. The description does not add additional parameter semantics beyond the schema, so it stays at the baseline for 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 specifies 'Read the current value of a checkpoint by key' with a clear verb and resource. It distinguishes from sibling tools (set_state, list_state, etc.) by describing the read semantics and return format.

  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 clear context for when to use the tool: to retrieve a stored checkpoint value. It does not explicitly mention alternatives or exclusions, but the sibling tool names make the distinction obvious.

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

• set_stateA
  4.7/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 explains atomicity, version guard semantics, and conflict-safe behavior. The only minor gap is not explicitly stating what happens on version mismatch (e.g., fails vs. returns error), but it implies the write is conditional and conflict-safe, which is sufficient.

  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 three sentences with zero filler. It front-loads the core function, then details the version guard parameter, and ends with the alternative tool. Every sentence earns its place, making it appropriately sized for the 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?

  Given the tool has 3 parameters and no output schema, the description is highly complete. It covers the write semantics, version guard options, and when to use alternatives. It even mentions the recommended way to obtain expected_version from get_state, forming a complete usage context.

  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 documents all three parameters with 100% coverage, so the baseline is 3. The description adds value by explaining the expected_version semantics in detail (0=create-only, N=versioned update, omit/-1=unconditional) and clarifying that value must be a JSON-encoded string, which goes beyond the schema's brief description.

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

  Purpose5/5

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

  The description clearly states the tool's core function: 'Atomically write a checkpoint with optional version guard.' It uses a specific verb ('write') and resource ('checkpoint'), and distinguishes itself from sibling tools by mentioning force_set_state as an alternative for simpler writes. This makes the purpose unambiguous.

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

  Usage Guidelines5/5

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

  The description provides explicit guidance on when to use this tool vs. alternatives: 'Use force_set_state for simpler unconditional writes.' It also explains the different expected_version modes (create-only, conditional update, unconditional), which tells the agent exactly in what scenarios to use this tool.

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