Server Quality Checklist

Tool Scores

• get_profileA
  3.9/5.0
  Behavior3/5

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

  Annotations provide readOnlyHint=true, so the safety profile is covered. The description adds that it returns '完整人物画像' including all fact entries and their factIds, which is useful return-context. But it doesn't disclose behavior like pagination, limits, or whether facts are returned in any particular order. With readOnlyHint covering the main concern, a 3 is appropriate.

  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 concise sentences, no wasted words. Front-loaded with the primary purpose, followed immediately by source guidance for the id. Every word earns 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?

  The tool has an output schema, so return-value explanation is not needed. It has a single required parameter that is adequately explained. Given the low complexity and presence of output schema and readOnlyHint annotation, the description is reasonably complete. It could briefly mention that facts are listed with factIds (which it does), and the provenance of the id is covered.

  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?

  Schema description coverage is 0%, so the description must carry the burden for the single profileId parameter. The description clarifies the id's provenance ('通常来自 search_profiles 或 list_profiles'), effectively explaining what profileId means and where to get it. With only 1 parameter, this compensation is sufficient.

  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 ('按 id 读取完整人物画像') and specifies what's returned (全部事实条目及其 factId). It distinguishes itself from sibling read tools but doesn't explicitly name them as alternatives.

  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 on when to use this tool — it states the id '通常来自 search_profiles 或 list_profiles', which gives the agent guidance on how ids are obtained and implies this is the retrieval tool for a known id. However, it doesn't explicitly state when NOT to use it versus alternatives like search_profiles.

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

• update_factA
  4/5.0
  Behavior2/5

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

  注释提供了 idempotentHint=true，描述没有与其矛盾。但描述没有补充注释之外的行为信息——例如修改是覆盖还是合并、是否影响历史记录、是否有权限要求。作为修改类工具（非读取），描述承担了较多的行为披露责任，但未提供额外语境。

  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.

  Completeness3/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  工具较复杂（6 参数、2 枚举、修改操作），有 output schema 可解释返回结构。描述说明了核心用法（何时改 vs 追加）和 factId 来源，这对主要使用场景是足够的。但未描述修改的成功/失败行为、对相关条目的影响、或枚举参数含义，扣分。若无 output schema 则会更不足。

  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?

  Schema 覆盖率为 0%，6 个参数中有 2 个 required（profileId、factId）。描述提到了 factId 的来源（"factId 来自 get_profile"），为参数添加了 schema 之外的有用语义。不过其他参数（content、source、category、confidence）未在描述中说明，但考虑到 0 覆盖率，描述做的补偿优于基线水平。

  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?

  描述明确说明"修改画像中某一条已有事实"，动词+资源明确（update fact）。它通过说明与 add_facts 的区别来区分于兄弟工具，说明此工具用于改写已有条目而不是追加新条目。中文标题"修正事实条目"也清晰表达了用途。

  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?

  给出了明确的用法指导："信息过时时（换工作、搬城市）应改写原条目，而不是用 add_facts 追加一条互相矛盾的新事实"。这明确说明了何时使用此工具、何时不用，并直接命名了替代工具 add_facts。

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

• delete_factA
  4.1/5.0
  Behavior4/5

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

  The destructiveHint annotation already declares the destructive nature, so the bar is lower. The description adds valuable context beyond the annotation: that clearing all facts leaves an empty profile shell that still surfaces in search/results, that there is no profile-deletion tool in this server, and that manual file deletion is the correct path for whole-profile removal. This meaningfully enriches the behavioral picture beyond the bare annotation.

  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 wordy for the warnings it conveys — it's a single focused paragraph that packs when-to-use, when-not-to-use, and a strong misuse warning into a compact space. Every sentence earns its place; no filler or tautology.

  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 is deceptively simple (2 params) but has a significant misuse pitfall (clearing whole profiles). The description thoroughly addresses this trap and the alternative path. An output schema exists, so return-value documentation isn't required. The only remaining gap is parameter-level detail (what factId looks like), but overall this is well-covered for a simple destructive 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 0%, so the description carries the full burden for explaining the two parameters. However, the description does not explain what factId and profileId refer to beyond their obvious names, nor the format/type of each. The concept of a 'fact' is implied by '事实条目' but never formally tied to the factId parameter. Given 0% coverage and only 2 simple parameters, the baseline should compensate, but the description adds minimal parameter-specific semantics.

  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 it deletes a single fact from a profile ('从画像中删除一条事实'), with a specific verb and resource. It distinguishes from siblings by explicitly contrasting with update_fact and warning against clearing entire profiles, though the sibling differentiation is embedded within usage warnings rather than a standalone purpose statement.

  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?

  Excellent guidance: explicitly states when to use (information confirmed incorrect or no longer relevant), when NOT to use (outdated info should use update_fact instead), and explicitly warns against using it to clear entire profiles. It also names the alternative tool (update_fact) and explains the consequence of misuse (a hollow shell that still appears in search and duplicate detection).

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

• create_profileA
  4.2/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 behavioral burden. '创建画像' implies creating a new record, and the description warns about duplicates, which is useful behavioral context. However, it does not disclose whether this is a read or write operation's safety profile, or any other behavioral traits beyond the duplicate handling.

  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 concise sentences, front-loaded with the core purpose, then actionable guidance. Zero wasted words. Each sentence earns its place - the first states the primary function, the second gives critical preconditions and fallback 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?

  The tool has an output schema, so return-value explanation isn't needed. The description covers the key preconditions (check for duplicates), the merge fallback, and mentions the duplicateCandidates mechanism. Given the moderate complexity (5 params, all documented in schema) and the presence of an output schema, this is reasonably complete. Could mention ideal fact categories or data quality but is adequate overall.

  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 5 parameters (name, facts, aliases, summary, relationship). The description adds the important context that 'duplicateCandidates' being non-empty signals potential duplicates, which clarifies the return/output semantics. However, it doesn't add much depth to individual parameter meaning beyond what the schema's property descriptions already provide.

  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?

  Description clearly states the purpose: create a profile for a new person ('为一个新的人创建画像'). It names the specific verb+resource and lists the tool's primary function. It also distinguishes itself from sibling tools like search_profiles, update_profile, and add_facts by explicitly naming them.

  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?

  Excellent usage guidance. It explicitly instructs to check search_profiles first to confirm no existing profile, and tells the agent what to do when duplicateCandidates is non-empty: switch to update_profile/add_facts to merge. This is explicit when-to-use and when-not-to-use with named alternatives.

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

• update_profileA
  4.2/5.0
  Behavior4/5

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

  Beyond the idempotentHint annotation, the description adds important behavioral details: only explicitly passed fields are modified, and aliases are incrementally merged without deleting existing ones. This partial-update and merge semantics is critical behavioral context that annotations don't cover. Could potentially note auth requirements but the core semantics are well disclosed.

  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?

  Three concise sentences with zero waste. Every sentence adds distinct value: what fields, the partial-update behavior, the merge behavior, and the sibling tool diversion. Well front-loaded with purpose then semantics.

  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 is a partial-update mutation with 5 params, an output schema exists, and annotations provide idempotency. The description covers the essential semantics (partial update, merge behavior, sibling routing) well. Could add a note about return values, but the output schema covers that responsibility. Adequate for the tool's complexity.

  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 only 20%, so the description bears responsibility for clarifying params. It clarifies aliases semantics (incremental merge, not delete) and states which fields are modified (name, relationship, summary, aliases), adding meaning beyond the schema. However, coverage is low and the description doesn't detail relationship or summary constraints beyond the schema's basic types.

  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 (修改/update) and specific fields (姓名/name, 关系/relationship, 摘要/summary, 别名/aliases). It distinguishes from siblings by explicitly naming add_facts / update_fact / delete_fact for fact operations. Could be slightly stronger in naming the tool's distinct role vs create_profile, but the field-level scope is clear.

  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 the incremental merge behavior ('只有显式传入的字段会被修改') and explicitly directs users to use add_facts / update_fact / delete_fact for fact operations, providing clear exclusions and alternatives. This is strong when-to-use vs when-not-to guidance.

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

• search_profilesA
  4.3/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, which covers the safety profile. The description adds that it returns a 'lightweight list' and does fuzzy matching, which is useful but doesn't detail pagination, match quality, or ordering 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?

  Two dense sentences, no waste. Front-loaded with the core purpose and then usage guidance. Could be slightly more structured but efficiently communicates both what and when.

  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?

  With an output schema present and readOnly annotation covering safety, the description covers the key elements: purpose, search fields, return type (lightweight list), and when to use. The tool is a simple search, so completeness is adequate for its complexity.

  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?

  Schema coverage is only 50% (limit documented with min/max/default, query documented as text). The description enriches the query parameter by explaining it accepts name, alias, summary, or facts content — adding semantic meaning beyond the schema's generic '姓名、别名或任意关键词'. The limit parameter is well-covered by 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?

  Clear verb+resource+scope: fuzzy search of profiles by name, alias, summary, or recorded facts, returning lightweight list. Differentiates from siblings by specifying it's a pre-write lookup tool (avoid duplicate creation).

  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?

  Explicit usage context: call before recording or querying someone's info to confirm existing profile and avoid duplicate creation. This gives clear when-to-use guidance and implies the alternative is to proceed with create_profile if no match.

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

• list_profilesA
  4.5/5.0
  Behavior4/5

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

  The description states the result is a summary ('摘要') rather than full profiles, which is meaningful behavioral context. The ordering behavior (reverse chronological by update time) is also disclosed. With readOnlyHint=true already in annotations, the safety profile is covered, and the description adds the summary-vs-full disclosure that annotations don't 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?

  Two crisp sentences, front-loaded with the core action and ordering. The alternative tool reference is packed into one clause. Zero wasted words, perfectly concise.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness5/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  This is a simple paginated list with an output schema present, so the return structure is already documented. readOnlyHint is annotated. Two trivial params are self-documenting. The description fully covers purpose, ordering, and the sibling distinction. There's nothing meaningful left undisclosed for a read-only list tool.

  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 0%, but both parameters (limit, offset) are standard pagination parameters whose meaning is self-evident from their names and numeric defaults. The description doesn't add parameter semantics, but the parameters are low-complexity (integer limit/offset with defaults). Baseline 3 is appropriate given the trivial parameter semantics.

  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?

  Clearly states the verb (list), resource (profiles), scope (all), and ordering (most recent update first). Explicitly distinguishes from search_profiles, which handles keyword retrieval. The Chinese title '列出人物画像' reinforces the resource and action.

  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?

  Explicitly states when to use this tool ('用于浏览', for browsing) and explicitly names the alternative for keyword searching ('按关键词检索请用 search_profiles'). This is a clear when-to-use with a named alternative, exactly matching the high standard.

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

• add_factsA
  4.6/5.0
  Behavior4/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 does disclose the deduplication behavior (facts matching existing content are skipped and reported in skipped) and the anti-contradiction guidance. However, it does not mention potential issues like append-only semantics, whether facts are immutable, or return structure beyond skipped. Still, the dedup and skip reporting are meaningful disclosures given zero 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 compact — two sentences total — and every sentence earns its place. The first sentence states the primary function and dedup behavior; the second provides the critical alternative-tool guidance. No filler, no redundancy, and the most important differentiating guidance is front-loaded in the correction sentence.

  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 a well-structured schema (enum categories, confidence with default) and an output schema, the description covers what's most critical beyond the schema: dedup behavior and correction routing. It lacks some depth around edge cases (e.g., what 'skipped' means structurally, whether the tool returns the created fact IDs), but for a moderate-complexity tool with strong schema support, this is adequate-to-good. The correction routing is the highest-value missing-schema context and it's present.

  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?

  Schema description coverage is 0%, so the description must compensate. It explains the semantic concept of facts (content added to a profile) and the dedup behavior, but does not detail the individual parameters (profileId, facts, category, source, confidence). However, the schema itself is richly self-descriptive with enums and defaults for category and confidence, so the schema does the heavy lifting for parameter semantics. The description adds the behavioral meaning around dedup and correction.

  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 (append facts), the resource (existing profile), and key behaviors (deduplication via skipped reporting, correction handling via update_fact). It explicitly distinguishes the tool from the sibling update_fact by clarifying that corrections should use the sibling instead. The scope and behavior are specific and immediately actionable.

  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 (appending new facts to an existing profile), and provides a clear exclusion: if the fact is a correction (e.g., job change), use update_fact instead to avoid contradictory entries. It names the sibling tool and explains the rationale, giving the agent concrete decision guidance.

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