Server Quality Checklist

Tool Scores

• get_pew_historyB
  3.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 burden. It adds useful behavioral context: the expected input shape ({date, score, level}), the architectural role (facade per ADR-007, storage owned by M3), and a design constraint (zero cross-package imports). However, it does not disclose whether the operation is read-only, whether merging into the timeline has side effects, or failure behavior — '并入' (merge) is ambiguous about mutation.

  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 compact — three short sentences with the core purpose front-loaded ('PEW 历史聚合 facade'). It avoids filler. The ADR-007 reference and '零跨包 import' are niche implementation details that add limited value for an agent, but they are brief and do not significantly bloat the text.

  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?

  An output schema exists, so return values are covered elsewhere, and the description adequately conveys the data contract and architectural role. However, with no annotations and 0% schema coverage on parameters, the missing usage guidance and the ambiguous side-effect profile of the merge operation leave the description incomplete for safe agent invocation.

  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 0% schema description coverage, the description must compensate, and it partially does: it documents pew_history as the M3 get_pew_history output with entries of {date, score, level}, adding meaning beyond the schema's generic 'array of objects with additionalProperties'. However, patient_id is left unexplained, and it is unclear when pew_history should be supplied versus left as the default null.

  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 function: aggregate PEW history data from M3 (list of {date, score, level}) into a unified follow-up timeline, which gives a clear verb+resource. It is contextually distinct from siblings like schedule_followup and get_adherence_score. However, the architectural jargon 'facade,' the ADR-007 reference, and the mismatch between the name 'get_pew_history' (suggesting retrieval) and the described merge/aggregation behavior introduce some ambiguity.

  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 when-to-use guidance, no alternatives named, and no exclusions are provided. The only implicit hint is '接受 M3 get_pew_history 的输出' (accepts M3 get_pew_history output), which suggests it is for integrating M3-sourced data, but the description never says when to choose this tool over siblings or what prerequisites must be met.

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

• get_adherence_scoreA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden. It discloses the side effect of recording, which conflicts with the name 'get', and provides the calculation method. However, it lacks details on idempotency, permissions, or what happens on repeated calls.

  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 compact three-sentence summary covering purpose, formula, and thresholds without waste. Every sentence contributes to understanding the tool.

  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?

  The core calculation logic is fully specified, but usage guidance, complete parameter descriptions, and side-effect clarity are missing. An output schema exists, so return values are not required, but selection and invocation context is incomplete.

  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%, so the description must compensate. It explains the three ratio parameters and their range, but does not describe the 'caller' parameter or explicitly map patient_id to schema fields, leaving gaps.

  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 calculates and records an adherence score, with explicit formula and grading thresholds. It is distinctly different from sibling tools (followup scheduling, records, PEW history).

  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?

  Usage is implied for adherence scoring, but no explicit when-to-use or alternatives are mentioned. The description notes M4 owns the adherence data, which gives context but does not exclude other tools.

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

• get_followup_recordsA
  4.2/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses a key behavioral trait: role-dependent filtering (doctor notes stripped for patient/family). It also explicitly labels the operation as 'read' and notes all roles can read, implying non-destructive behavior. Lacks details like pagination or error handling, but the critical access-control behavior is well-covered.

  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 only two sentences, front-loaded with the core action and read-only nature, then adding the role-based detail. Every sentence earns its place with no redundancy or filler.

  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 output schema exists and parameters are simple, the description covers the essential context: what is read, who can read what, and the fact it's a read operation. It doesn't explain the 'plan timeline' fully, but that's a minor omission for a read tool with an output schema.

  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 must add meaning. It does explain the 'caller' parameter implicitly via role lists (clinical vs patient/family) and its effect on visibility. However, 'patient_id' is not explicitly described, and the mapping between parameter names and description is indirect, leaving some ambiguity.

  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 reads follow-up records and plan timeline, with an explicit 'read' label and role-based access. It distinguishes itself from siblings like schedule_followup (write) and get_adherence_score/get_pew_history by focusing on reading follow-up records as a distinct resource.

  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 (to read follow-up records) and explains visibility rules based on caller role. It doesn't explicitly mention alternatives/exclusions, but the role scoping makes the intended use clear enough.

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

• schedule_followupA
  4.2/5.0
  Behavior4/5

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

  No annotations are provided, but the description discloses key behavioral traits: it's a write operation with restricted roles, automatically computes follow-up frequency per KDIGO 2024, and defines field-level visibility (plan_summary visible to all, note_to_clinician restricted). It also states the return includes next_due_date. It does not mention error handling, idempotency, or auth requirements, but covers critical behavior.

  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 two concise sentences, front-loaded with the core purpose and role restriction, followed by a compact parameter legend. Every clause adds value with no fluff.

  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 write tool with 8 parameters and no annotations, the description covers purpose, access control, algorithm, key parameters, and return value. The output schema is present, so return details are covered. Missing edge-case behavior and some parameter meanings reduce completeness slightly, but it's strong 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 0%, so the description must compensate. It explains ckd_stage allowed values (G1-G5D), anchor_date format, and visibility semantics for plan_summary and note_to_clinician. However, it leaves caller, visit_type, albuminuria_stage, and patient_id unexplained, so coverage is partial.

  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 '创建' (create) and resource '随访计划' (follow-up plan), explicitly noting it is a write operation ('写') with role restrictions. It differentiates from sibling read tools (get_followup_records etc.) by its creation focus and mentions automatic KDIGO calculation.

  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 access context (only doctors/nutritionists/orchestration layer) and indicates the tool is for creating follow-up plans with automatic frequency calculation. It does not explicitly mention when not to use it or compare to siblings, but the write-vs-read distinction is implicit. The 'MX 收口' note clarifies scope.

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