Server Quality Checklist

Tool Scores

• searchA
  3.7/5.0
  Behavior3/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, idempotentHint=true, and openWorldHint=true, covering safety and behavior. The description adds context about the marketplace scope and return format (skills with name, description, author, stars, GitHub URL), but does not disclose additional traits like rate limits, authentication needs, or pagination details beyond what annotations imply.

  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 appropriately sized with two paragraphs: one for purpose and one for parameters/returns. It is front-loaded with the main purpose, but could be more concise by integrating parameter details more seamlessly rather than a separate list.

  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 (5 parameters, 100% schema coverage, annotations covering key behaviors, no output schema), the description is mostly complete. It explains the purpose, parameters, and return values, though it could benefit from more usage guidance relative to siblings.

  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 the schema fully documents all 5 parameters. The description lists parameters with examples and defaults, but adds minimal meaning beyond the schema (e.g., 'query' example 'fastapi', 'react testing' is similar to schema's 'SEO', 'web scraper'). Baseline 3 is appropriate as 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 searches the 'SkillsMP marketplace for AI coding skills by keywords', specifying both the action (search) and resource (AI coding skills in SkillsMP marketplace). It distinguishes from sibling tools like 'install_skill', 'read_skill', and 'remove_skill' which perform different operations on skills, and from 'ai_search' which likely has a different scope or method.

  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 skills by keywords, but does not explicitly state when to use this tool versus alternatives like 'ai_search' or other siblings. It provides context for searching the marketplace but lacks explicit guidance on exclusions or comparisons with other tools.

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

• install_skillA
  3.8/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false, destructiveHint=false, idempotentHint=false, and openWorldHint=true. The description adds some behavioral context by explaining the installation scope implications (user-level vs project-level) and listing valid agent values. However, it doesn't describe important behavioral aspects like what happens on failure, whether installations are reversible, or how the tool interacts with existing skills. The description doesn't contradict 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?

  The description is well-structured with a clear opening statement followed by organized parameter explanations and a complete example. Each sentence serves a purpose, though the parameter explanations could be slightly more concise. The information is front-loaded with the core purpose stated first. Minor verbosity in parameter formatting prevents a perfect score.

  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?

  For a 4-parameter mutation tool with no output schema, the description provides adequate but incomplete context. It covers parameter usage well but lacks information about return values, error conditions, or what constitutes successful installation. The annotations provide safety profile (non-destructive, non-idempotent), but the description doesn't fully compensate for the missing output schema by explaining expected results.

  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 100% schema description coverage, the baseline is 3. The description adds meaningful value by providing concrete examples (e.g., 'anthropics/claude-code' for source, 'frontend-design,backend-dev' for skills), clarifying the format of comma-separated values, and explaining the boolean meaning of 'global' parameter with specific path implications. The description enhances understanding beyond the schema's technical specifications.

  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 specific verb ('Install') and resource ('skills from GitHub to AI coding agents'). It distinguishes from sibling tools like 'read_skill' and 'remove_skill' by specifying installation rather than reading or removal. The opening sentence provides immediate clarity about what the tool does.

  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 context through parameter explanations (e.g., 'global' parameter defines installation scope), but doesn't explicitly state when to use this tool versus alternatives like 'remove_skill' or 'read_skill'. No explicit guidance is provided about prerequisites, error conditions, or when not to use this tool. The example shows typical usage but doesn't provide comparative guidance.

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

• remove_skillA
  3.9/5.0
  Behavior4/5

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

  Annotations already indicate destructive (true) and idempotent (true) operations, but the description adds valuable behavioral context: 'Removes the skill directory and associated symlinks from the agent's skills directory' clarifies what gets destroyed and the scope of removal. It doesn't contradict annotations and provides implementation details beyond the structured hints.

  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 a clear purpose statement followed by parameter explanations and implementation details. While somewhat verbose in repeating schema information, every sentence contributes to understanding. It could be more front-loaded by moving the 'Removes the skill directory...' sentence earlier.

  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 destructive tool with good annotations and full schema coverage, the description provides adequate context about what gets removed and scope implications. Without an output schema, it doesn't describe return values, but the operational details are sufficiently covered for the tool's complexity level.

  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?

  With 100% schema description coverage, the schema already documents all parameters thoroughly. The description repeats parameter information (skills format, agent options, global scope meaning) but doesn't add significant semantic value beyond what's in the schema. Baseline 3 is appropriate when 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 specific action ('Remove installed skills') and target resource ('from an AI coding agent'), distinguishing it from siblings like 'install_skill' and 'read_skill'. It provides a complete operational picture beyond just the tool name.

  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 context through parameter explanations (global vs project scope, agent selection) but doesn't explicitly state when to use this tool versus alternatives like 'read_skill' or 'install_skill'. No explicit guidance on prerequisites or when-not-to-use scenarios is provided.

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

• ai_searchA
  4.4/5.0
  Behavior4/5

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

  Annotations already provide comprehensive behavioral hints (read-only, non-destructive, idempotent, open-world), so the bar is lower. The description adds valuable context beyond annotations by explaining the AI-powered semantic nature and intent understanding, which helps the agent anticipate how queries are processed. No contradictions with annotations exist.

  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 well-structured and front-loaded with the core purpose, followed by usage guidelines, parameters, and examples. Every sentence earns its place without redundancy, making it efficient and 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 moderate complexity, rich annotations covering safety and behavior, and 100% schema coverage, the description is mostly complete. It lacks details on output format or result structure, but since there's no output schema, this is a minor gap. The description adequately complements the structured data for agent use.

  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%, providing detailed parameter documentation. The description adds minimal value beyond the schema, only mentioning the 'query' parameter with examples but not elaborating on 'response_format'. Since the schema does the heavy lifting, the baseline score 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 clearly states the tool's purpose with specific verbs ('semantic search for skills') and resources ('skills'), distinguishing it from sibling tools like 'search' by emphasizing AI-powered natural language understanding. It explicitly mentions the AI component and natural language queries, which differentiates it from keyword-based alternatives.

  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 ('Use this when keywords aren't enough - describe what you want to accomplish'), offering a clear alternative scenario (keyword-based search) and distinguishing it from the sibling 'search' tool. It effectively tells the agent when this tool is preferred over other search methods.

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

• read_skillA
  4.4/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=true, covering safety and idempotency. The description adds valuable behavioral context beyond annotations: it specifies what happens when the path has no skill.md ('returns directory listing'), which is not inferable from annotations alone. However, it doesn't mention rate limits or authentication needs.

  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 front-loaded with the core purpose in the first sentence, followed by usage guidance and parameter details. Every sentence earns its place: the first states what it does, the second when to use it, and the parameter section clarifies behavior and defaults. No wasted words.

  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 read-only tool with comprehensive annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) and full schema coverage, the description is mostly complete. It explains the tool's purpose, usage context, and fallback behavior. However, without an output schema, it could benefit from more detail on return values (e.g., format of directory listing).

  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 the schema already fully documents all parameters. The description repeats parameter names and provides examples (e.g., 'anthropics', 'claude-code'), but doesn't add significant semantic meaning beyond what's in the schema. The baseline of 3 is appropriate when 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 verb ('Read') and resource ('skill file content (SKILL.md) from a GitHub repository'), distinguishing it from sibling tools like install_skill and remove_skill. It specifies the exact file being read (SKILL.md) and the source (GitHub repository), making 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 explicitly states when to use this tool ('Use to preview a skill before installing'), providing clear context for its application. It also distinguishes from alternatives by focusing on previewing rather than installing or removing skills, which are handled by sibling tools.

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