Server Quality Checklist

Tool Scores

• qa_session_appendB
  3/5.0
  Behavior2/5

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

  No annotations are present, so the description must disclose behavior, but it only says 'Append one Q&A entry to session file.' There is no mention of whether existing data is preserved, what happens if the session file does not exist, required permissions, or return behavior. The one-question rule is a conversational convention, not a tool behavior disclosure.

  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 short sentences, front-loaded with the main action 'Append one Q&A entry to session file.' Every word earns its place, and the one-question rule adds relevant constraint without 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?

  With four parameters, no annotations, and no output schema, this description is too thin. An agent would likely struggle to know what kind values map to, what understanding_pct means, or how session paths should be formatted. It is minimally viable but leaves critical gaps.

  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 coverage is 0%, and the description does not explain session_path, kind, content, or understanding_pct. The phrase 'Q&A entry' loosely hints that content relates to one of the kind enum values, but it does not map parameters to their purpose or explain the optional understanding_pct field.

  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 appends a Q&A entry to a session file, which gives a specific verb and resource. It does not explicitly differentiate from siblings like qa_session_start, but 'append' and 'session file' make the core purpose understandable.

  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 instruction 'Ask only ONE question per chat turn' provides some workflow guidance, but the description does not explicitly say when to use this tool versus alternatives like qa_session_start or estimate_context. Usage is mostly implied by the tool name and append semantics.

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

• qa_session_startB
  3.1/5.0
  Behavior2/5

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

  No annotations are provided, and the description only mentions creating a file; it does not disclose what happens if the file already exists, whether workspace/directory is created, or any return/error handling behavior. For a mutation tool with zero annotation coverage, this is a major gap.

  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?

  Single sentence with an embedded target file path and condition; no filler or 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?

  The tool is simple and the description is adequate for creating a file, but the lack of an output schema, annotations, and a note about the behavior of the parser/existing files makes the context less exhaustive.

  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?

  Input schema coverage is only ~33% (1 of 3 properties has a description). The description adds no real meaning for 'slug' or 'task_summary' beyond the schema; renaming the default text would help.

  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?

  Description clearly states it creates a task-specific markdown session file (adhd/sessions/YYYY-MM-DD-slug.md) and ties it to starting Q&A for a task. This is distinct from sibling append/readiness/footer tools, though no alternatives are explicitly named.

  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?

  Description gives a when-to-use context ('when starting Q&A for a task') but does not explicitly state when not to use it or what sibling tools (e.g., qa_session_append) should be used instead.

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

• estimate_contextB
  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 must convey behavior fully. It only mentions that the tool estimates or accepts a reported percentage, but does not disclose what it returns, whether it modifies state, or any edge cases. The sequencing hint is minimal.

  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 sentences with no filler. It front-loads the core action and provides a clear workflow hint.

  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?

  With 5 parameters, no annotations, and no output schema, the description is too sparse. It does not explain return values, parameter semantics, or how the result is used by format_status_footer beyond the ordering note.

  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 parameter description coverage is 0%, so the description should compensate. It does not explain any of the five parameters (turn_count, rules_chars, conversation_chars, mcp_overhead_chars, context_percent_reported) or their roles in the estimation logic.

  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 uses specific verbs 'Estimate or accept' and clearly identifies the resource as context window usage %. It also references 'format_status_footer', which distinguishes this tool from siblings by its role in a workflow.

  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 explicitly states when to call: 'before format_status_footer when IDE ring % is unknown.' This gives clear timing and condition. However, it does not explicitly exclude other scenarios or name alternatives, leaving some room for improvement.

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

• format_status_footerB
  3.4/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 burden. It reveals that the tool builds a mandatory footer and requires char counts, which is somewhat behavioral. However, it doesn't disclose what the footer looks like, how it displays progress bars, or any side effects. It's a light description that could add more detail about the output format or constraints (e.g., what happens if counts are missing).

  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 short and for the most part to the point, with a specific instruction. One slight issue: the mixed language ('Pass THIS TURN char counts for 本轮 tok') may reduce clarity, but it's still compact. It front-loads the purpose and key instruction. Not a 5 due to the minor bilingual phrase that might confuse.

  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 has 12 parameters, no output schema, and no annotations, the description is under-specified. It tells the user to pass char counts but doesn't explain how parameters like understanding_pct, progress_pct, turn_count, conversation_chars, or include_progress_bar are used. A more complete description would detail required fields and behaviors. The complexity is moderate-high, and the description doesn't fully cover it.

  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 50%: only 6 out of 12 parameters have descriptions (reply_chars, tool_call_count, tool_result_chars, user_message_chars, turn_tokens_reported, reply_tokens_reported). The tool description doesn't add meaning for the undocumented parameters like turn_count, conversation_chars, include_progress_bar, context_percent_reported, or the required understanding_pct/progress_pct. It mentions 'char counts' generally but doesn't map to specific params. Baseline 3 because coverage is 50% and description partially helps but leaves gaps.

  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 builds a mandatory ADHD reply footer and specifies the key input (char counts for this turn). It distinguishes itself from siblings like check_readiness and qa_session_tools by focusing on footer formatting. However, it doesn't explicitly name sibling tools or contrast its function with them, so not a 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 phrase 'Pass THIS TURN char counts' gives some usage guidance, implying the user should supply metrics for the current interaction. However, it doesn't explain when to use this tool vs alternatives (e.g., when to use estimate_context vs format_status_footer), nor does it state any conditions or exclusions. Minimal guidance.

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

• check_readinessA
  3.8/5.0
  Behavior3/5

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

  With no annotations provided, the description carries the full burden. It discloses the return type (whether understanding ≥95%) and a system policy (edits forbidden when false), but does not explicitly state that the tool is read‑only, has no side effects, or what happens if the parameter is out of range. For a simple predicate, this is adequate but leaves some behavioral details implicit.

  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 single sentence, immediately states the core return condition, and includes the consequential rule. There is zero fluff, and the key information is front‑loaded. Perfectly concise for the tool's complexity.

  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 has only one parameter, no output schema, and no annotations, the description covers the essential behavior (what it returns and the implication for code edits). It does not mention additional context like error handling or side effects, but all of that is likely unnecessary for such a simple check. The description is nearly complete, lacking only an explicit note on read‑only behavior.

  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% (the description never mentions the parameter by name), so the description must compensate. It indirectly references understanding but does not explicitly explain that 'understanding_pct' is the basis of the check. The schema constraints (0–100) are clear, and the parameter name is self‑explanatory, but the description adds little beyond what the schema already conveys.

  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 returns a boolean based on whether understanding is ≥95%, and it explicitly ties the result to whether code edits are allowed. This specific outcome distinguishes it from siblings like estimate_context or format_status_footer, which serve different purposes.

  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 the tool should be used as a gating check before code edits (since edits are forbidden when ready=false), but it never explicitly says 'use this before editing' or names alternatives. There is no direct comparison to sibling tools or when-not-to-use guidance, only a behavioral consequence.

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