Server Quality Checklist

Tool Scores

• couplingA
  3.9/5.0
  Behavior4/5

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

  Annotations already mark the tool as read-only and idempotent, and the description goes beyond this by explaining the behavioral basis: the tool relies on commit co-occurrence rather than static import statements. This adds meaningful context about how the analysis works.

  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 and front-loaded: the first sentence explains the core concept, and the second gives the practical use case. It is economical, though the phrase 'dependencies no import statement reveals' is slightly awkward and could be clearer.

  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?

  For a read-only tool with three optional, fully documented parameters and no output schema, the description provides enough context for an agent to understand what it does, when to use it, and what kind of results to expect (file pairs). It does not detail the output format, but the concept is straightforward.

  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 fully documents repo, min_support, and min_confidence. The description does not add parameter-specific guidance, but the baseline of 3 is appropriate since the schema carries the load.

  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 core function: identifying file pairs that frequently co-occur in the same commits, revealing implicit dependencies not visible via imports. It is clear enough to distinguish it from a generic 'list files' tool, though it does not explicitly name sibling 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 a concrete usage context: 'Use it to learn what else an edit usually drags along before touching a file.' This tells an agent when to invoke it, though it does not mention when not to use it or point to alternative tools.

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

• briefA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds genuine behavioral context by stating the tool is a composite read and enumerating its returned facets. This goes beyond the annotations without contradicting them, though it does not discuss cost, pagination, or response structure.

  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, both dense and purposeful. The first sentence front-loads the core value proposition and the second gives a precise sibling contrast. There is no filler or repetition of schema content.

  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 no output schema, the description carries the burden of explaining what the call returns, and it does so by listing the major data categories. The terms 'ratchet mark' and 'change-coupling partners' rely on domain context that sibling tools help establish, but the overall picture is sufficiently complete for selection and invocation. Optional parameters are not mentioned, though the schema already documents them.

  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 baseline is 3 and the schema already explains all three parameters clearly. The description adds no parameter-specific details, which is acceptable because the parameter descriptions are already strong. It does not need to compensate for any schema 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 identifies the tool as a single-call read that gathers a function's full context, enumerating the included data: scored row, ratchet mark, uncovered lines, duplication twins, churn, and change-coupling partners. It lacks an explicit imperative verb like 'retrieve' or 'get', but 'the deepest single read' communicates the action and scope effectively. It also distinguishes itself from the sibling tool 'explain', helping an agent understand its unique role.

  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 context by calling this 'the deepest single read' and positioning 'explain' as 'the slimmer history-only view.' This implies an agent should choose this tool when comprehensive context is needed and 'explain' when only history matters. It does not explicitly mention exclusions relative to other siblings like 'duplication' or 'coupling', but the selected contrast is useful and concrete.

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

• explainA
  4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is established. The description adds useful output context (trajectory, ratchet mark, and that brief adds fuller context), but it does not go deeper into behavioral details such as how runs are ordered or what exactly the ratchet mark represents.

  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 with no filler. The first sentence defines the output scope, and the second provides usage guidance plus the sibling alternative. Every sentence earns its place and the key information is front-loaded.

  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?

  For a simple read-only lookup tool, the description covers what the tool returns, why to use it, and how it differs from a related sibling. The params are fully documented in the schema and the annotations cover side effects. It could name the return format more explicitly, but an agent has enough to invoke it correctly.

  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 parameter descriptions already document name, path, and repo well, including matching behavior for 'name' and defaults for 'repo'. The tool description itself adds no parameter-specific semantics, so the baseline of 3 applies.

  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 states a specific resource ('one function's score trajectory across runs plus its ratchet mark') and a clear use ('see whether a function is improving or decaying'). It also distinguishes itself from the sibling 'brief' by noting that brief adds full context around the newest score, so an agent can tell them apart.

  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?

  It gives explicit guidance on when to use the tool ('Use it to see whether a function is improving or decaying') and points to 'brief' as the alternative for full context. It does not discuss other siblings, but the main decision point is covered.

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

• runsA
  4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds behavioral context beyond annotations by specifying ordering ('newest first') and the exact fields returned, which helps the agent know what to expect. It does not contradict the 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 compact sentences contain the essential information: what the tool returns and when to use it. There is no filler or repetition of schema/annotation data. The field list is front-loaded, and the usage guidance is immediately actionable.

  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?

  For a simple read-only list tool, the description is nearly complete: it lists the output fields, states ordering, and explains the tool's purpose in relation to the other tools. There is no output schema, but the description supplies the key return information. Minor ambiguity remains around the meaning of 'kind' and 'verdict' values, but it does not block correct 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?

  The only parameter, repo, is fully described in the schema with its default behavior. Schema description coverage is 100%, so the description does not need to add parameter semantics. The tool description adds no extra parameter detail, but the baseline of 3 applies because the schema already carries the full burden.

  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 identifies the tool as a run-history listing tool and enumerates the returned fields: id, kind, verdict, commit, and lane set. It does not use an explicit verb like 'list', but the resource and scope are unmistakable. It also gives a purpose ('date the store', 'check which commit the other tools answer from') that differentiates it from the sibling tools.

  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?

  'Use it to date the store or to check which commit the other tools answer from' provides explicit, concrete use cases. It does not mention alternatives or when not to use it, but the context is clear enough for an agent to select it appropriately among siblings.

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

• duplicationA
  4.1/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, covering the safety profile. The description adds useful behavioral detail about how it works: normalized line shingles and a containment percentage. There is no contradiction with the 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 two focused sentences with no filler. The first sentence states the output and method; the second provides a concrete use case. It is easy to scan and every sentence earns its place.

  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?

  For a read-only analysis tool with two optional parameters and no output schema, the description is complete enough: it says what the tool finds, how it computes similarity, what metric is returned, and when to use it. No critical information is missing for an agent to call it correctly.

  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 100%, with both parameters fully documented including the default and range for 'similarity.' The description reinforces the 'containment' concept but adds no new parameter-level detail beyond the schema, so the baseline of 3 applies.

  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 identifies the tool's subject ('near-duplicate function pairs') and its method ('normalized line shingles'), plus the metric it returns ('containment percent'). It lacks an explicit verb like 'find' or 'list,' but the intent is unambiguous. It does not explicitly differentiate from sibling tools, but the narrowly defined purpose makes confusion unlikely.

  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 gives explicit guidance on when to use the tool: 'Use it before a refactor.' It also explains the benefit, folding twins together instead of fixing one copy alone. It does not name alternatives or exclusions, but the use case is clearly stated.

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

• worklistA
  4.2/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the description doesn't need to repeat those. The description adds useful behavioral context: the tool returns the entire risk ranking with a specific ordering rule and a queue structure. This is beyond what annotations convey, and there is no contradiction.

  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. The primary purpose is front-loaded, and the sibling reference is efficiently included in the second sentence. Every word contributes value.

  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?

  For a read-only, idempotent tool with two optional parameters and no output schema, the description covers the essential purpose, ordering, and usage context. It does not describe return format or limits, but given the annotations and schema, there are no critical gaps for an agent to call it correctly.

  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%, with both top and repo parameters fully described. The description itself does not add parameter-specific semantics beyond what the schema provides, so the baseline of 3 applies. It doesn't repeat or enhance parameter details.

  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 what the tool does: it provides the run's whole risk ranking, with a specific ordering (ccn times recency-weighted churn). It explicitly differentiates from the sibling next_item (

  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 tells the agent to use it for surveying the repo and explicitly contrasts it with next_item. This gives concrete guidance on when to select this tool over at least one sibling, and the context (whole ranking vs one packet) is clear. It doesn't address all other siblings, but the primary alternative is covered.

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

• ratchet_reportA
  4.3/5.0
  Behavior4/5

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

  With readOnlyHint and idempotentHint already declared, the description adds useful behavioral context by specifying the data source (git history) and the report contents (open ratchet marks, ages, repayment velocity). This is especially valuable because there is no output schema.

  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 deliver the report's substance and its intended use without any filler. The key concept, 'debt burn-down,' is front-loaded, and every phrase earns its place.

  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?

  For a single-optional-parameter read-only tool, the description and schema together provide output contents, data source, and usage purpose. Nothing essential is missing for an agent to decide when to call this tool and what it will receive.

  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%, and the single repo parameter is already fully documented with its default behavior. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate.

  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 identifies the tool as a debt burn-down report covering open ratchet marks with their age and repayment velocity from git history. The final sentence states its purpose explicitly: 'Use it to see whether marked debt is being paid down or piling up.' This subject matter distinguishes it from siblings like coupling, duplication, and worklist.

  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 gives a clear intended use case: determining whether marked debt is being paid down or accumulating. It does not name alternatives or provide when-not-to-use guidance, so it misses the explicit exclusion that would earn a 5.

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

• doctorA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, so the description does not need to restate safety. It adds value beyond annotations by describing what the check covers and framing it as a first-line diagnostic. No contradiction with the read-only annotation; the tool plainly inspects configuration rather than mutating it.

  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 short sentences deliver the core function, the specific checks performed, and the precise usage context. There is no filler or redundant restatement of the tool name. The description is front-loaded and every sentence 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?

  For a simple read-only diagnostic with one optional parameter, the description is complete enough: it names the exact problems it detects and when to run it. It does not describe the return format, but the absence of an output schema and the nature of the tool make this a minor gap rather than a critical omission.

  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 single parameter 'repo' has full schema description coverage ('path to the scored repo's root (default: the repo the server was started in)'). The tool description does not add parameter-level detail, but with 100% schema coverage, the schema already carries the necessary meaning. Baseline 3 is appropriate.

  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 identifies the tool as a diagnostic check for config and repo agreement, enumerating specific failure modes it detects (typo keys, empty scopes, missing lane cwds, unresolvable runners). This is far more specific than a generic tool name and gives an agent a concrete model of the tool's function, distinguishing it from analysis-oriented siblings like coupling or duplication.

  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 second sentence gives explicit trigger conditions: 'Run it first when any other tool answers strangely or an expected file is missing from the ranking.' This tells the agent exactly when to invoke doctor versus other tools, which is ideal usage guidance for a diagnostic tool.

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

• next_itemA
  4.5/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true and idempotentHint=true, covering safety. The description adds selection logic (highest-risk) and return contents (score, uncovered lines, effort estimate, verify commands), which is useful context beyond 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 concise sentences with no filler, front-loading the core purpose and the routing to the alternative. Efficient and well-structured.

  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?

  All three parameters are optional and fully documented in the schema. There is no output schema, but the description explains the return contents, making the tool fully invocable without missing information.

  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%, with clear descriptions for top, repo, and exclude. The description adds no parameter-specific guidance, so the baseline 3 applies.

  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?

  States a specific action (return next item) and resource (highest-risk function to refactor), and describes the packet contents. Explicitly contrasts with sibling worklist, so it is clearly distinguishable.

  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?

  Gives explicit guidance: 'Reach for it when you want one item to act on' and names the alternative 'worklist is the same ranking as a survey.' This tells an agent when to use this versus siblings.

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