Server Quality Checklist

Tool Scores

• github_skills_get_skillB
  3/5.0
  Behavior3/5

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

  Annotations already indicate this is a read-only, non-destructive, idempotent, and open-world operation, covering key behavioral traits. The description adds minimal context by specifying 'key files,' but doesn't elaborate on what constitutes 'key' files, potential rate limits, or authentication needs. It doesn't contradict annotations, so a baseline score is appropriate given the annotations provide substantial information.

  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, clear sentence that efficiently conveys the core action. It's front-loaded with the main purpose and avoids unnecessary details. However, it could be slightly more informative by hinting at parameters or usage context without sacrificing brevity.

  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 presence of annotations (which cover safety and behavior) and an output schema (which handles return values), the description doesn't need to explain those aspects. However, with 0% schema description coverage and no parameter guidance, it falls short in providing a complete understanding of how to use the tool effectively, especially for parameter semantics.

  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?

  The schema description coverage is 0%, meaning parameters are undocumented in the schema. The description mentions 'specific skill directory' but doesn't explain parameters like 'skill_slug,' 'max_files,' or 'response_format.' It fails to compensate for the lack of schema documentation, leaving the agent with unclear parameter meanings beyond what's inferred from property names.

  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 action ('Fetch') and target ('key files for a specific skill directory from GitHub'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like 'github_skills_search_skills' or 'github_skills_list_repositories', which might also involve fetching skill-related data but with different scopes or methods.

  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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing a skill slug from search results, or compare it to siblings like 'github_skills_install_skill' for installation purposes or 'github_skills_search_skills' for finding skills. This leaves the agent without clear context for tool selection.

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

• github_skills_install_skillB
  3.3/5.0
  Behavior3/5

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

  Annotations indicate this is a non-read-only, non-destructive, non-idempotent, open-world operation, which the description aligns with by implying a download action that writes to disk. The description adds context about downloading to a local folder, but doesn't elaborate on potential behaviors like file system changes, error handling, or rate limits beyond what annotations provide.

  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 directly states the tool's purpose without unnecessary words. It's front-loaded and appropriately sized for its function, making it easy to parse quickly.

  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 tool's complexity (involving GitHub downloads and local file operations), annotations cover safety aspects, and an output schema exists, but the description lacks details on parameters, error cases, or integration with sibling tools. It's minimally adequate but has clear gaps in providing a complete operational 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 0%, but the description doesn't add any parameter details beyond the tool name's implication of a 'skill' and 'install'. It doesn't explain parameters like 'skill_slug', 'destination_dir', 'overwrite', or 'preserve_repo_prefix', leaving semantics unclear. With low coverage, the description fails to compensate, resulting in a baseline score.

  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 action ('Download') and target ('a skill directory from GitHub into a local folder'), which is specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'github_skills_get_skill' or 'github_skills_suggest_skill_scaffold', which might involve similar GitHub skill operations but with 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'github_skills_get_skill' or 'github_skills_search_skills', nor does it specify prerequisites, such as needing a GitHub repository or local directory permissions, leaving usage context unclear.

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

• github_skills_list_repositoriesA
  3.6/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=false, covering safety and idempotency. The description adds value by specifying the scope ('configured for this MCP server'), which isn't captured in annotations, providing useful context about the data source. No contradictions with annotations are present.

  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 directly states the tool's purpose without unnecessary words. It's front-loaded and wastes no space, making it easy for an agent to parse quickly.

  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 low complexity (one parameter, read-only, idempotent) and the presence of annotations and an output schema, the description is reasonably complete. It covers the core purpose and scope, though it lacks usage guidelines. The output schema likely handles return values, reducing the need for detailed output explanation.

  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 0%, with one parameter ('response_format') documented only in the schema with a description and enum. The description doesn't mention parameters at all, so it adds no semantic value beyond the schema. However, with only one parameter and an output schema available, the baseline is met without compensation.

  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 action ('List') and resource ('GitHub skill repositories configured for this MCP server'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'github_skills_search_skills' or 'github_skills_get_skill', which might have overlapping or related functionality.

  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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context, or exclusions, leaving the agent to infer usage from the tool name alone. For example, it doesn't clarify if this lists all repositories or filtered ones compared to 'search_skills'.

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

• github_skills_search_skillsA
  3.6/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and idempotency. The description adds minimal behavioral context by specifying the search scope ('skill names and paths'), but does not detail aspects like rate limits, authentication needs, or pagination. With annotations providing core behavioral traits, the description adds some value but not rich additional disclosure.

  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 directly states the tool's purpose without unnecessary words. It is front-loaded with the core action and target, making it easy to parse. Every part of the sentence contributes meaning, earning 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?

  Given the tool's moderate complexity (search operation with multiple nested parameters), annotations cover key behavioral traits (read-only, idempotent, etc.), and an output schema exists (implied by context signals), the description is reasonably complete. It specifies the search scope but could improve by mentioning output handling or error conditions. However, with annotations and output schema, it meets most needs, though not fully exhaustive.

  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 has 100% description coverage for its single parameter 'params' (which nests query, repo, limit, response_format), with detailed field descriptions. The description adds no parameter-specific semantics beyond implying a general search query. Given high schema coverage, the baseline is 3, as the description doesn't enhance parameter understanding beyond what the schema already provides.

  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 action ('Search') and target ('skill directories'), specifying that matching occurs against 'skill names and paths'. It distinguishes this from siblings like 'get_skill' (retrieve specific skill) and 'list_repositories' (list repos), though not explicitly. However, it doesn't fully differentiate from 'suggest_skill_scaffold' (which might involve search-like functionality), keeping it at 4 rather than 5.

  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 usage for searching skill directories, but provides no explicit guidance on when to use this tool versus alternatives like 'get_skill' for retrieving a specific skill or 'suggest_skill_scaffold' for scaffolding suggestions. It lacks clear when/when-not instructions or named alternatives, relying on context from tool names only.

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

• github_skills_suggest_skill_scaffoldA
  3.8/5.0
  Behavior4/5

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

  Annotations already indicate read-only, non-destructive, idempotent, and open-world behavior. The description adds valuable context: it specifies the tool creates scaffolds 'grounded in similar GitHub skills' and uses 'closest existing skills as examples,' clarifying the grounding mechanism beyond what annotations provide. 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.

  Conciseness5/5

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

  The description is a single, efficient sentence that front-loads the core action ('Create a grounded starter scaffold') and purpose ('using the closest existing skills as examples'). No wasted words or redundant information.

  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 moderate complexity (creation with grounding), rich annotations (covering safety and behavior), and presence of an output schema (which handles return values), the description is reasonably complete. It could improve by detailing parameter interactions or error cases, but it adequately complements the structured data.

  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 0%, so the description carries full burden. It mentions 'closest existing skills as examples,' which hints at the 'limit' parameter for grounding, but doesn't explain 'request' (user capability) or 'response_format.' With 1 parameter (nested object with 3 sub-parameters), the description adds minimal semantic value beyond 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 states the verb ('Create') and resource ('grounded starter scaffold for a new skill'), specifying it uses existing skills as examples. It distinguishes from siblings like 'get_skill' (retrieval) or 'install_skill' (deployment), but doesn't explicitly contrast with 'search_skills' (which might find similar skills without creating scaffolds).

  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 usage when starting a new skill development by leveraging examples, but lacks explicit guidance on when to use this versus alternatives like 'search_skills' for discovery or 'list_repositories' for raw data. No exclusions or prerequisites are mentioned.

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