Server Quality Checklist

Tool Scores

• list-yuque-docsC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool returns a list with basic information (title, slug, update time), which is helpful. However, it doesn't disclose important behavioral traits like whether this is a read-only operation, pagination behavior, rate limits, authentication requirements, error conditions, or what happens when namespace isn't provided (though the schema mentions default namespace). For a list operation with zero annotation coverage, this leaves significant gaps.

  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 concise with two sentences that directly address purpose and return value. The first sentence states what the tool does, and the second describes the return format. There's no wasted text or unnecessary elaboration. However, it could be slightly more front-loaded by integrating the return information into the purpose statement for even tighter structure.

  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 moderate complexity (list operation with one optional parameter), no annotations, and no output schema, the description is minimally adequate. It covers the basic purpose and return format but lacks important contextual information about behavioral traits, usage guidelines, and error handling. The absence of output schema means the description should ideally provide more detail about the return structure, but it only mentions basic fields without format or examples.

  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 description coverage is 100%, with the single parameter 'namespace' well-documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema. It mentions '指定知识库' (specified knowledge base) which aligns with the namespace parameter, but provides no additional context about format, examples, or usage. With high schema coverage, the baseline of 3 is appropriate as the description doesn't compensate but doesn't need to.

  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 purpose with a specific verb ('列出' meaning 'list') and resource ('指定知识库中的所有文档' meaning 'all documents in the specified knowledge base'). It distinguishes from sibling tools like 'get-yuque-doc' (retrieves a single document) and 'search-yuque-docs' (searches documents), but doesn't explicitly differentiate from 'get-yuque-toc' (which might list table of contents). The purpose is clear but sibling differentiation could be more explicit.

  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 when to prefer 'list-yuque-docs' over 'search-yuque-docs' for filtering, or when 'get-yuque-toc' might be more appropriate. There's no discussion of prerequisites, context, or exclusions. The only implied usage is when you want to list all documents in a knowledge base, but no comparative guidance is given.

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

• search-yuque-docsC
  2.9/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 mentions that searching occurs in document titles and descriptions, which adds some behavioral context. However, it lacks details on permissions, rate limits, pagination, or what happens if no matches are found. For a search tool with zero annotation coverage, this is insufficient.

  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 concise with two sentences that directly state the tool's function and scope. It's front-loaded with the main purpose, though it could be slightly more structured by explicitly mentioning parameters or usage context.

  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 complexity of a search tool with no annotations and no output schema, the description is incomplete. It doesn't explain return values, error handling, or how results are formatted. The mention of keyword matching in titles and descriptions is helpful but insufficient for full contextual understanding.

  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 documents both parameters ('query' as search keywords and 'namespace' as knowledge base namespace). The description implies the 'namespace' parameter specifies the knowledge base but doesn't add meaning beyond what the schema provides. 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.

  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 purpose: '在指定的知识库中搜索文档' (search for documents in a specified knowledge base). It specifies the verb '搜索' (search) and resource '文档' (documents), but doesn't explicitly differentiate from sibling tools like 'list-yuque-docs' or 'get-yuque-doc' beyond mentioning keyword matching in titles and descriptions.

  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 like 'list-yuque-docs' (which might list all documents) or 'get-yuque-doc' (which retrieves a specific document). It mentions searching within a knowledge base but doesn't specify scenarios where searching is preferable to listing or getting.

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

• get-yuque-tocB
  3.1/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 of behavioral disclosure. It describes what the tool does (gets TOC structure) but lacks critical behavioral details: it doesn't mention whether this is a read-only operation, potential rate limits, authentication requirements, error conditions, or the format of the returned data. For a tool with no annotation coverage, this is a significant gap in transparency.

  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 concise with two sentences that directly address the tool's function and capabilities. The first sentence states the core purpose, and the second adds useful context about what can be viewed. There's no wasted language, though it could be slightly more structured with explicit usage guidance.

  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 tool has no annotations, no output schema, and the description lacks behavioral details, the description is incomplete. It adequately explains what the tool does but fails to address how it behaves, what it returns, or important contextual factors. For a tool that presumably returns structured data, the absence of output information is particularly problematic.

  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 description coverage is 100%, with the single parameter 'namespace' fully documented in the schema. The description doesn't add any parameter-specific information beyond what's in the schema. According to the rules, when schema coverage is high (>80%), the baseline is 3 even with no param info in the description, which applies here.

  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 purpose: '获取语雀知识库的完整目录结构（TOC）' (Get the complete table of contents structure for Yuque knowledge base). It specifies the verb ('获取' - get) and resource ('目录结构' - TOC structure), and distinguishes it from siblings by focusing on hierarchical structure rather than listing or searching documents. However, it doesn't explicitly differentiate from 'list-yuque-docs' which might also provide some structural information.

  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 by mentioning '可以查看知识库中所有文档的层级结构、标题和 slug' (Can view the hierarchical structure, titles, and slugs of all documents in the knowledge base), suggesting it's for understanding document organization. However, it doesn't explicitly state when to use this tool versus alternatives like 'list-yuque-docs' or 'search-yuque-docs', nor does it provide any exclusions or prerequisites.

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

• get-yuque-docA
  3.6/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. It discloses key behavioral traits: it's a read operation (implied by '获取'), returns detailed information including content and stats, and supports multiple input formats. However, it lacks details on error handling, rate limits, authentication needs, or response structure. For a tool with no annotations, this is adequate but leaves gaps in operational 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?

  The description is well-structured and concise. It starts with a clear purpose statement, then lists supported input formats with examples, and finally enumerates the returned information in a bulleted list. Every sentence adds value without redundancy, 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 moderate complexity (3 parameters, no output schema, no annotations), the description is fairly complete. It covers the purpose, input methods, and return data. However, without an output schema, it could benefit from more detail on the response format (e.g., structure of '文档完整内容'). Still, it provides sufficient context for basic usage, justifying a score above minimum viable.

  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 documents all three parameters thoroughly. The description adds value by explaining the two input formats and how parameters interact (e.g., '如果提供了 docUrl 则忽略此参数' for namespace), but doesn't provide additional semantic meaning beyond what's in the schema. This meets the baseline for high schema coverage.

  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 purpose: '获取文档的详细信息' (get detailed information about a document) from Yuque. It specifies the resource (Yuque document) and the action (retrieve details). However, it doesn't explicitly differentiate from sibling tools like 'get-yuque-toc' (which likely gets table of contents) or 'list-yuque-docs' (which likely lists documents), so it's not a perfect 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 provides usage context by detailing two supported input formats (URL vs. namespace+slug), which implies when to use each format. However, it doesn't explicitly state when to use this tool versus alternatives like 'search-yuque-docs' or 'get-yuque-toc', nor does it mention any prerequisites or exclusions. This leaves some ambiguity for the agent in selecting between siblings.

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