Server Quality Checklist

Tool Scores

• query_libraryC
  2.4/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden for behavioral disclosure. It does not reveal return format, whether it's a read-only operation (though 'query' implies read), pagination, or how the has_lyrics filter behaves for null values. Since an output schema exists, some return info is covered, but behavioral traits are otherwise undisclosed.

  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 short sentence, which is efficient and free of waste. It is appropriately brief, though slightly under-specified. No unnecessary content or redundant restatement of the tool name.

  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?

  The tool has 3 parameters, 0% schema coverage, no annotations, but does have an output schema which reduces some explanatory burden. However, the description is minimal and does not explain filter behavior, defaults, or how results are sorted/ordered. For a query tool with siblings offering similar functionality, more context is needed to disambiguate tool choice.

  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?

  Schema description coverage is 0%, meaning no parameters are documented in the schema itself. The description mentions keyword and has_lyrics filters (matching two of the three parameters), but does not explain the meaning, range, or behavior of 'limit' or the exact filter semantics. Given 0% coverage, the description must compensate but only partially covers two parameters.

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

  Purpose3/5

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

  The description states it queries the local library with keyword and lyrics filters. The verb 'query' plus 'local library' defines a clear purpose, but it does not differentiate from the sibling 'search_songs' which likely overlaps in functionality. The scope is somewhat clear but sibling differentiation is missing.

  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 on when to use this tool versus the sibling 'search_songs'. It does not specify exclusions or alternative tools. The description gives context that it targets the local library, but there is no explicit when/when-not guidance or mention of alternatives.

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

• scan_libraryC
  2.7/5.0
  Behavior2/5

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

  No annotations are provided, so the description carries full burden. The description mentions '补元数据并触发歌词补全' (supplement metadata and trigger lyric completion), implying a mutating operation that modifies the library. However, it does not disclose what exactly gets changed, whether it's destructive, whether network access is required for lyric fetching, or what happens to existing metadata.

  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, compact sentence that wastes no words. It efficiently conveys the two core actions (scan + metadata + lyrics). Not verbose, but the brevity comes at the cost of missing depth described in other dimensions.

  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?

  For a 1-param mutating tool with no annotations, no schema coverage, the description is too thin. It does not explain the return value/output format (output schema exists but description could add context), what metadata fields are supplemented, the side effects of the scan, or failure modes. The description would benefit from stating what kind of directory, what metadata is added, and what the scan does to existing entries.

  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?

  Schema description coverage is 0%, and the single required param 'dir' is entirely undocumented in both schema and description. The description does not explain what 'dir' should be (a filesystem path? a library identifier?), what format, or what constraints apply. Given 0% coverage, the description must compensate but provides no parameter details whatsoever.

  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 states the verb (扫描/san) and resource (本地音频目录/local audio directory) with clear actions: supplement metadata and trigger lyric completion. It distinguishes from siblings like search_songs and query_library, which are query-oriented, while scan_library is a write/scan operation on a directory.

  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 explicit guidance on when to use this tool versus the alternatives. The description implies it's for scanning/batch operations, but does not clarify when one would choose scan_library over query_library or search_songs, nor state what prerequisites or consequences apply.

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

• search_songsC
  2.8/5.0
  Behavior2/5

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

  无任何注释提供，描述承担全部行为披露责任。描述仅列出返回字段，未说明搜索匹配逻辑（模糊/精确匹配）、是否区分大小写、排序行为、收录范围或外部来源行为。作为搜索工具，缺少对搜索执行细节的披露。

  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?

  单句描述，简洁高效。直接说明功能并列出返回字段，没有冗余信息。结构清晰，价值密度高。

  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?

  有输出schema存在可减轻返回格式负担，但仅2个参数却有0% schema描述覆盖率，且无注释，描述未解释参数含义和搜索行为。作为搜索工具，这个简洁度不足以支撑实际使用，特别是缺少与query_library的区分说明。

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters1/5

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

  schema描述覆盖率为0%，描述应完全补偿参数说明，但描述完全未提及任何参数。'query'的含义（关键词格式、是否需要精确匹配）和'limit'（上限默认值）均未在描述中说明。两个参数均无任何语义补充。

  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?

  描述明确说明了工具功能——按关键词搜索歌曲，并列出了返回的字段（标题/歌手/专辑/来源/是否已入库）。动词'搜索'+资源'歌曲'清晰。与兄弟工具有所区分（其他工具涉及下载、歌词、扫描、查询），但未明确说明与query_library的区别。

  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?

  描述暗示了'搜索歌曲'的用途，但没有明确说明何时使用此工具而非query_library等替代工具。没有排除条件或前置要求。搜索场景implied但未具体说明与其他库查询工具的区别。

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

• download_songB
  3.3/5.0
  Behavior2/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. It discloses download behavior but doesn't mention key behavioral details like whether files are overwritten on conflict, what the output/return format is (though output schema exists), whether it requires authentication, or error conditions. For a file-writing operation with zero annotation coverage, the transparency is limited.

  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, zero filler. The first sentence states the core purpose and parameter modes. The second sentence explains the default behavior for an optional parameter. Every word earns its place. Excellent concision.

  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 output schema exists (structuring the return), the description doesn't need to explain return values. However, this is a file-mutation tool with 4 parameters at 0% schema coverage and no annotations. The description covers the essential parameter logic (either/or modes, default dir) but lacks behavioral context like conflict handling and prerequisites. Slightly above minimum viable but incomplete for a download/mutation operation.

  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?

  Schema description coverage is 0%, and the description only partially compensates. It explains the relationship between norm_key and title+artist (either-or), and that target_dir defaults to a config value when omitted. But it doesn't explain the format of norm_key, whether title/artist must both be provided together, or constraints on directory paths. At 0% schema coverage, the description should do more heavy lifting for all 4 parameters.

  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 states a specific verb+resource ('下载歌曲到本地' - download song to local). The purpose is clear: downloads a song to local storage. It doesn't explicitly distinguish from siblings, but siblings like search_songs, get_lyrics, scan_library are obviously different in function, so the differentiation is reasonably clear from the nature of the 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?

  The description provides clear usage guidance: pass norm_key (from search results) OR title+artist. It also explains that target_dir defaults to MUSIC_MCP_DOWNLOAD_DIR config when omitted. This gives the agent clear direction on parameter selection. However, it doesn't explicitly state when NOT to use this tool versus alternatives, though the distinction is fairly apparent.

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

• get_lyricsA
  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 full behavioral disclosure burden. It discloses the tool WRITES a .lrc file (a side effect beyond simply retrieving), explains the file location logic (audio_dir provided vs MUSIC_MCP_LYRICS_DIR config fallback). Notably the description reveals this is not purely a read operation—it persists to disk—which is valuable behavioral transparency absent from any 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?

  Two crisp sentences, zero filler. Every clause adds value: LRC preference, identification options, and write-location logic. Highly efficient and front-loaded with the core 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?

  The tool mutates the filesystem (writes .lrc), has 5 parameters all undocumented in schema, and no annotations—yet the description conveys the essential write behavior, identification options, and output-location logic. It covers the core complexity well; minor gaps include what duration_ms affects (LRC timing?) and return value behavior, though an output schema exists to cover return structure.

  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 bears full responsibility. It explains the meaning of norm_key and title+artist (identification methods) and audio_dir (output location), which covers 3 of 5 parameters. However, duration_ms and the precedence of norm_key vs title+artist semantics are not clarified beyond what the schema shows.

  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 (获取/retrieve lyrics), the resource (lyrics for a song), and a specific preference (LRC format prioritized). It distinguishes from siblings—search_songs is for searching not retrieving lyrics, download_song downloads audio not lyrics. The purpose is specific and action-oriented.

  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?

  It explains the two ways to identify a song ('传 norm_key 或 title+artist'), giving usage direction. However, it doesn't mention when to choose this vs siblings or any exclusions/alternatives, so the when-to-use guidance is implied rather than explicit.

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