Server Quality Checklist

Tool Scores

• sync_skillsC
  2.9/5.0
  Behavior2/5

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

  Annotations are absent, so the description must disclose behavioral traits. It only mentions the act of synchronization and the target locations, but does not clarify the direction of sync, potential side effects (e.g., overwriting files), or whether this is a read or write operation. This is insufficient for a mutation 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 a single, concise sentence with no fluff. It leads with the verb and primary resource, though the phrase 'with your personal skill collection... and global cache' is slightly ambiguous. Overall, it is efficient and front-loaded.

  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?

  Given the absence of output schema and annotations, the description is too thin. It fails to explain return values, side effects, or how this tool relates to sibling tools. For a sync operation with potential file mutations, this lacks critical context for an agent to use safely.

  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% with both parameters (configPath, projectPath) having meaningful descriptions. The tool description adds little beyond the schema, only reinforcing the config path. Baseline 3 is appropriate since the schema already documents the parameters adequately.

  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 with a specific verb 'Synchronize' and names the resources involved: project workspace skills, personal skill collection (~/.ai-skills/skills.config.json), and global cache. It distinguishes from sibling tools by implying a broader sync operation rather than install/remove/list, though it doesn't explicitly contrast them.

  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 provided on when to use this tool versus alternatives like install_skills or remove_skills. There is no mention of appropriate contexts, prerequisites, or exclusions, leaving the agent without direction on tool selection.

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

• check_missing_skillsA
  3.9/5.0
  Behavior3/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 usefully discloses that installation is not triggered, but it does not clarify what 'status' means, whether any state is modified, or what the output format looks like. This is a moderate gap for a tool with no 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.

  Conciseness5/5

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

  The description is a single, focused sentence that conveys the core operation and a key caveat with no filler or wasted words.

  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?

  Given the lack of output schema and annotations, the description is somewhat thin. It explains the check action but not what constitutes 'status' or the nature of the returned result. The parameter descriptions help, but overall the tool could benefit from clarifying expected outputs or side-effect guarantees.

  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 parameters are already documented. The description does not add extra meaning beyond the schema, matching the baseline for full 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 tool's purpose with a specific verb ('check') and resource ('status of project skills'), references the merged config file, and explicitly notes it does not trigger installation. This distinguishes it from sibling tools like sync_skills and install_skills.

  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 implies usage when a read-only status check is needed without installation, which contrasts with sync/install siblings. However, it lacks explicit when-not-to-use or alternative tool recommendations.

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

• remove_skillsA
  3.9/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 of disclosure. It does disclose the removal location and metadata tracking, but it does not mention that removal is likely irreversible, what happens to bundles containing multiple skills, or what 'update metadata tracking' means in practice. This leaves important behavioral context implicit.

  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, front-loaded sentence that states the action, target, location, and side effect in order. It contains no redundant or filler words and is easily scannable by an agent.

  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 tool is a mutation with no output schema, and the description covers the action and location. However, it lacks indication of expected return behavior, confirmation of success, or consequences for bundled skills. For a destructive operation, more detail on reversibility and side effects would improve completeness.

  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 parameters (skills, projectPath, removeFromConfig) are already fully documented. The description adds no new parameter detail beyond referring to 'specified skills or bundles', which mirrors the skills parameter. Baseline of 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 uses the specific verb 'Remove' and clearly identifies the resource ('skills or bundles') and the location ('.agents/skills'). It also notes the side effect of updating metadata tracking, distinguishing it from siblings like install_skills or sync_skills.

  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 context makes the purpose clear—removing skills or bundles—and the verb 'remove' contrasts naturally with 'install' or 'sync'. However, it does not explicitly state when to prefer this tool over alternatives or mention exclusions (e.g., when not to use it).

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

• get_workspace_infoA
  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 carries the full burden. The verb 'inspect' implies a read-only operation, but the description does not explicitly state that no changes are made, nor does it describe the return value or error behavior. It adds some transparency but leaves gaps.

  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 sentence that front-loads the tool's purpose ('Debugging tool') and enumerates specific aspects concisely without redundancy.

  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 a simple signature (one optional param, no output schema), and the description covers the main purpose. However, it could name the return value or clarify what 'validity' entails, but it's reasonably complete for a debugging helper.

  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 provides a clear description of 'projectPath' with 100% coverage, so the tool description doesn't need to add more. It doesn't, which is acceptable.

  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 ('inspect') and resource ('active project workspace'), enumerating concrete aspects (resolution, detection source, protection status, validity). It differentiates from sibling tools which are all setup/management actions.

  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 phrase 'Debugging tool' provides clear context for when to use it (during troubleshooting), and the read-oriented verb 'inspect' distinguishes it from the action-oriented siblings. However, it doesn't explicitly mention when not to use it or alternative tools.

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

• list_installed_skillsA
  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 full burden. It discloses the operation is a listing, specifies the exact location (.agents/skills), and notes the inclusion of version metadata tracker details. This provides useful behavioral context, though it stops short of describing output format or side-effect absence.

  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, front-loaded sentence with no redundant words. It efficiently conveys the action, scope, and extra details.

  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 list operation with one optional parameter and no output schema, the description gives sufficient context about what is listed and where. It doesn't explain return shape, but the simplicity of the tool makes this a minor gap.

  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 provides a detailed description for projectPath, achieving 100% coverage. The tool description adds no parameter-specific meaning, 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?

  The description uses the specific verb 'List' and names the resource 'installed skills inside the project (.agents/skills)', also mentioning 'version metadata tracker details'. This clearly distinguishes it from sibling tools like install_skills, remove_skills, and sync_skills.

  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 intent is clear from the verb and scope, but there is no explicit guidance on when to use this tool versus alternatives such as get_workspace_info or sync_skills. Usage context is implied rather than stated.

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

• install_skillsA
  4.1/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of disclosing behavioral traits. It reveals that the tool uses workspace auto-detection, global cache, and version tracking, and it implies only missing skills are installed. However, it does not specify whether existing skills are overwritten, if network access is required, or any side effects, leaving some ambiguity.

  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 primary purpose and followed by key behavioral details. Every sentence contributes information without redundancy or excessive length.

  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?

  Given no output schema and no annotations, the description provides the core purpose and some behavioral details, but it lacks comprehensive coverage of side effects, prerequisites, or return behavior. It is adequate for basic understanding but not fully complete for an installer tool.

  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 fully covers both parameters with descriptions, giving a baseline of 3. The description adds value by explaining that workspace auto-detection can override projectPath and that the config can be project or global, which enriches the meaning of configPath and projectPath 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 clearly states the action ('Install'), the resource ('missing project skills defined in project/global skills.config.json'), and the destination ('.agents/skills'). The mention of 'missing' and 'version tracking' differentiates it from sibling tools like sync_skills or check_missing_skills.

  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 implies when to use the tool: to install missing skills based on configuration. It provides context about workspace auto-detection and global cache but does not explicitly name alternatives or when-not-to-use conditions. This is clear but lacks direct exclusions, so a score of 4 is appropriate.

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

• bootstrap_projectA
  4.2/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 of behavioral disclosure. It lists specific side effects: setting up .agents/skills, loading config, using global cache, installing missing skills, and updating .agents/skills-manager.json. This is transparent about the write operations. It does not mention potential caveats like overwriting existing files or requiring network access, but the disclosed actions are substantial and unlikely to mislead.

  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 sentence but efficiently packs all key information: the action (bootstrap), the scope (new or existing project workspace), and the specific steps. It is front-loaded with the primary purpose and avoids filler. Every clause contributes to understanding the tool's behavior.

  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 and the absence of an output schema, the description covers the main behaviors and artifacts affected. It does not describe return values or error scenarios, but the list of setup steps provides a solid understanding for an agent to select and invoke the tool. The presence of siblings adds context, and this description clearly positions bootstrap_project as the comprehensive setup action.

  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%: both configPath and projectPath have descriptions. The tool description adds no parameter-specific details beyond what the schema already provides. It mentions 'loading personal skill collection & project config' which may relate to configPath, but this is not explicit. The baseline of 3 is appropriate because 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 clearly states the tool's purpose: automatically bootstrap a new or existing project workspace. It lists concrete actions (setting up .agents/skills, loading personal skill collection & project config, using global cache, installing missing skills, updating version metadata tracker) which distinguish it from sibling tools like install_skills or sync_skills by being the comprehensive setup operation.

  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: when bootstrapping a new or existing project workspace. It does not explicitly mention exclusions or alternative tools, but the phrase 'bootstrap a new or existing project workspace' implies it is the go-to for full setup, leaving install_skills for targeted installs. However, explicit guidance on when not to use it (e.g., 'for single-skill installs, use install_skills instead') is missing.

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