Server Quality Checklist

Tool Scores

• vigil_deleteA
  4.2/5.0
  Behavior4/5

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

  DestructiveHint annotation already indicates destructive action; description adds value by mentioning disk reclamation and the caveat about artifact directories not being deleted, providing extra 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?

  Description is very concise with two sentences, no fluff, and covers essential information efficiently.

  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 tool with two parameters and no output schema, the description adequately covers the action and a notable caveat. Could mention irreversibility explicitly, but destructiveHint implies it.

  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% for both parameters. Description reinforces 'all' usage but does not add significant meaning beyond the schema definitions.

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

  Purpose5/5

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

  Description clearly states 'Delete a checkpoint and reclaim disk space' with a specific verb and resource. It distinguishes itself from siblings (diff, list, restore, save) by the delete action.

  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?

  Description provides clear context for deleting one or all checkpoints using the 'all' parameter, and advises about artifact directories not deleted. However, it does not explicitly state when not to use the tool.

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

• vigil_saveA
  4.2/5.0
  Behavior2/5

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

  The description says 'Runs in background — returns immediately,' adding behavioral context beyond annotations. However, the idempotentHint: true annotation conflicts with the verb 'Create,' which typically implies non-idempotent behavior. The description does not clarify idempotency, creating a contradiction.

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

  Conciseness5/5

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

  Two concise sentences: first defines core action, second gives critical usage warning. No redundancy, front-loaded.

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

  Completeness4/5

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

  Covers main behavior (background) and capacity handling. Lacks mention of return value or success/error indications, but no output schema is present. Reasonably complete given sibling 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?

  Schema coverage is 100%, but the description adds context: 'named checkpoint' hints at the 'name' parameter, and the full-slots warning relates to 'max_checkpoints.' No additional details on 'description' parameter are given.

  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 'Create a named checkpoint of the entire project,' specifying verb and resource. It differentiates from sibling tools like vigil_delete, vigil_diff, vigil_list, and vigil_restore by focusing on creation.

  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 instructs the agent: if slots are full, DO NOT auto-retry but ask the user to delete or increase capacity. This provides clear when-not-to-use and alternative actions, though does not compare to siblings directly.

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

• vigil_listA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint. Description adds that it shows disk usage and has dual behavior based on name, which aligns with annotations. No contradictions.

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

  Conciseness5/5

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

  Two sentences, front-loaded with main function, then variation for name. Every word earns its place; no redundancy or fluff.

  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 2-param tool with no output schema, description covers the main behaviors and mentions disk usage. Lacks details on output format or glob usage context, but sufficient for basic use.

  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%, providing baseline of 3. The description adds semantic context for the 'name' parameter (drill into checkpoint) beyond the schema, justifying a score of 4.

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

  Purpose5/5

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

  Description clearly states the tool lists checkpoints and disk usage, with specific behavior when a name is provided (drill into files). This distinguishes it from sibling tools (delete, diff, restore, save) and uses a specific verb+resource combination.

  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?

  Description implies usage: omit name for overview, provide name to list files. It does not explicitly exclude alternatives or mention when not to use, but sibling tools cover other actions, making the context clear.

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

• vigil_diffA
  4.6/5.0
  Behavior5/5

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

  The description adds rich behavioral context beyond annotations: it mentions 'full unified diffs', the summary option for faster results, and the capability to search across checkpoints. Annotations already indicate readOnly and idempotent, and the description does not contradict these. It fully informs the agent of safe, stateless behavior.

  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 extremely concise: two sentences that front-load the overall purpose and then enumerate specific capabilities without redundancy. Every word serves a purpose, and the structure is clear and easy to parse.

  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 (multiple operations, 5 parameters, no output schema), the description covers the core functionality well, explaining key parameter interactions and use cases. It does not detail return format or error handling, but enough context is provided for effective use.

  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%, baseline is 3. The description enhances parameter understanding with usage hints: e.g., name can be '*' for scanning, search requires name='*' and file, against enables cross-checkpoint comparison. This adds meaningful context beyond the schema's brief 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 clearly specifies the tool's purpose: to search and investigate previous versions of the codebase by comparing checkpoints or retrieving file contents. It distinguishes itself from sibling tools like vigil_delete, vigil_list, vigil_restore, and vigil_save through its focus on diffing and historical retrieval.

  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 usage scenarios: comparing checkpoints, retrieving file contents, and searching across checkpoints. It mentions parameter interactions (e.g., '*' with file+search for scanning all checkpoints). It lacks explicit when-not-to-use guidance but sufficiently implies that this tool is for investigation, not deletion or saving.

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

• vigil_restoreA
  4.7/5.0
  Behavior5/5

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

  Adds important context beyond the destructiveHint annotation: explains quicksave and that files are never deleted.

  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 precise sentences with main action first, 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?

  For a simple tool with one parameter and destructive annotation, the description covers behavior, safety, and alternatives fully.

  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?

  Single parameter has clear schema description ('Checkpoint name to restore'); tool description adds no additional nuance.

  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 'Restore project to a checkpoint state' and distinguishes from sibling tool vigil_diff for individual file restores.

  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 mentions that quicksave occurs first, files are preserved, and directs to vigil_diff for individual restores.

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