Server Quality Checklist

Tool Scores

• query_pattern_graphB
  3.4/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds the behavioral nuance of traversing contextual candidates and applying filters, plus the bounded nature of results. It does not describe output shape or pagination, but 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?

  The description is two sentences with no filler. The first sentence states the core functionality and filters, and the second gives clear usage guidance. Every sentence earns its place.

  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?

  Without an output schema, the description should at least sketch what the tool returns, but it only describes the traversal behavior. The optional parameters and their relationships are left ambiguous, so an agent may not know whether to provide text, seedPatterns, or just rely on defaults. Annotations provide safety context but not enough for a complete call.

  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 needs to compensate. It only references 'layer and cost filters', which maps to `layers` and `maxAdoptionCost`, and hints at `seedPatterns` via the phrase 'around a problem or seed'. The `text`, `limit`, and exact role of `seedPatterns` remain unexplained, leaving a significant gap for a tool with five parameters.

  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 identifies a specific action ('traverse contextual candidates and explicit pattern relationships') and scopes it with layer and cost filters. It also clarifies the intended use case ('bounded discovery around a problem or seed'), which distinguishes it from a broad catalog dump. It does not explicitly name sibling tools, but its purpose is still clear.

  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 'when to use' directive: bounded discovery around a problem or seed. It also provides a 'when not to use' warning: not to dump the entire catalog. However, it does not name any sibling alternatives or explain how this tool differs from them, so it stops short of a 5.

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

• write_pattern_adrA
  3.5/5.0
  Behavior4/5

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

  Annotations already establish read-only, idempotent, non-destructive behavior. The description adds meaningful context by clarifying the output is a proposed, non-final ADR and by listing the kind of content it records, which shapes agent expectations beyond 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?

  A single front-loaded sentence with no filler; every clause contributes either the action, the input source, or the output character.

  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 main purpose and output contents are covered, and no output schema exists to document the return shape. However, the description does not clarify the ADR's format/representation or how the large nested `case` object maps into the generated record, leaving some practical gaps for a complex input schema.

  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%, and the description only indirectly refers to `case` with 'from a case'; `title` receives no semantic explanation. The description does not compensate for the absence of schema descriptions on the two required parameters.

  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 uses a specific verb ('Generate') and resource ('architecture decision record'), and states what the output captures: considered options, uncertainty, validation metrics, open questions, and reversal triggers. It is clear, but it does not explicitly name or differentiate against sibling tools like analyze_design_case or plan_pattern_adoption.

  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?

  Use is implied: call this when a proposed ADR should be produced from a case. There is no explicit when/when-not guidance or mention of alternatives, so an agent must infer how this differs from the sibling planning/analysis tools.

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

• analyze_design_caseA
  3.7/5.0
  Behavior4/5

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

  The description discloses behavioral substance beyond the annotations: it specifies the tool returns rejected patterns, a non-pattern baseline, evidence plans, and a bounded pattern compound, and that it diagnoses before prescribing. Since annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, these output details add meaningful context about what the agent can expect.

  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 three sentences, front-loaded with the core purpose, followed by the return-value list, and ends with the usage instruction. No word is wasted; every sentence contributes a distinct piece of the operational picture.

  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?

  For a tool with a complex nested input schema and no output schema, the description gives the high-level output components and use case, but does not help the agent construct a well-formed 'case' object (e.g., what to put in 'team', 'scales', 'delivery'). The tool is fundamentally clear, but the missing parameter guidance leaves an agent with significant inference burden.

  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% for top-level parameters, so the description needed to compensate. Instead, it does not mention 'case', 'maxRecommendations', or any guidance on how to structure the input object beyond implying the user provides a design problem. The nested schema is rich but the agent gets no help from the description on what to populate.

  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 ('Diagnose forces') and clearly indicates the tool analyzes a design case to produce a pattern recommendation bundle. It lists concrete outputs ('questions, transparent scores, rejected patterns...'), which makes the tool's function identifiable. However, it does not explicitly distinguish itself from sibling tools beyond 'Use this first', so it stops short of 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 Guidelines4/5

  Does the description explain when to use this tool, when not to, or what alternatives exist?

  'Use this first for an open-ended design problem' explicitly tells the agent when to invoke this tool and gives it an ordering relative to the pipeline. It does not, however, mention when not to use it or name any specific sibling alternative, so it lacks the full when/when-not/alternatives coverage 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.

• plan_pattern_adoptionA
  3.8/5.0
  Behavior4/5

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

  Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds meaningful context beyond annotations: the plan is evidence-gated, starts with a baseline and smallest production slice, and includes exit criteria and rollback. 'Create' refers to generating a plan artifact, not a side-effecting mutation, so 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 front-loaded sentences with no filler. The first sentence states the action and constraints, and the second concisely lists the deliverable's required components.

  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 description tells the caller what the plan will contain and conveys the evidence-gating requirement, which is useful given there is no output schema. However, it does not describe the output format, explain how to populate `case`, or address potential edge cases for a complex nested input. This leaves important gaps for an agent.

  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 only elaborates the `pattern` parameter with 'one named pattern' and leaves the complex `case` object unaddressed. Given that `case` has many nested fields and no descriptions, the description provides minimal help for 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?

  The description names a specific verb ('Create'), a concrete resource ('reversible, evidence-gated adoption plan'), and a scope ('one named pattern'). It also enumerates plan components, which distinguishes it from siblings like compare_pattern_options or write_pattern_adr.

  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 clearly implies the tool is for planning adoption of a single, already-selected pattern, with evidence-gating and reversibility as requirements. However, it never explicitly says when to use it versus alternatives, and it does not mention any sibling tools or exclusion conditions.

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

• stress_test_pattern_decisionA
  3.9/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds behavioral context by listing the scenario dimensions and the outcome ('report when the leading decision flips'), but it does not describe the report format or any implicit constraints. This is adequate but not enriched 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 sentences, no filler, with the core action front-loaded and the usage tip in a separate concise sentence. Every word adds value.

  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 complex with nested objects, an array of patches, and no output schema. The description gives strategic context but omits operational details: what a 'flip' looks like, how to structure a scenario patch, and what the response contains. The schema provides structural guidance, but the absence of output/return behavior is a noticeable gap for a tool of this 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 0%, so the description must compensate. It does partially by naming the counterfactual dimensions (scale, delivery, consistency, team, evidence, goals), which maps to fields in the case object. However, it never explicitly explains the 'case' parameter or how to construct valid scenario patches, leaving significant semantic burden on the schema structure.

  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 a specific verb ('Apply') and resource ('pattern decision'), and clearly distinguishes the tool's function: applying counterfactual scenarios to see when the leading decision flips. This is a unique activity not covered by siblings like analyze_design_case or compare_pattern_options.

  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 use the tool ('Use before committing to expensive architecture'), providing clear temporal context. It does not mention alternatives or when not to use it, but the timing guidance is actionable.

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

• detect_pattern_misuseA
  4/5.0
  Behavior4/5

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

  Annotations already establish read-only, idempotent, and non-destructive behavior; the description adds that the audit covers existing and proposed patterns and surfaces hidden costs and simpler alternatives. No contradiction with 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 sentences, both earning their place: the first defines the audit scope and criteria, the second gives usage timing and an exclusion. Information is front-loaded with the action verb.

  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 has a rich nested `case` schema and no output schema, yet the description does not explain what `case` should contain or what kind of report to expect. The rich property names partially compensate, making this a minimum-viable level rather than a complete definition.

  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?

  With 0% top-level schema coverage, the description carries the burden of explaining parameters. It only maps to patternsInUse via 'patterns already used or proposed' and says nothing about the required `case` object or its role as the design context. This leaves a significant gap.

  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 opens with a specific verb 'Audit' and a target ('patterns already used or proposed'), then lists the concrete evaluation dimensions: cargo-cult risk, missing forces, hidden costs, and simpler alternatives. It explicitly distances itself from a generic pattern search, which separates it from siblings like query_pattern_graph.

  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 during design or code review, not as a generic pattern search' gives explicit when-to-use and when-not-to-use guidance. It does not name specific sibling alternatives, so it falls just short of the full 5.

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

• get_pattern_evidence_planA
  4/5.0
  Behavior4/5

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

  Annotations already establish read-only, idempotent, and non-destructive behavior. The description adds value by specifying the exact evidence-plan payload returned — hypothesis, measurements, experiment, rejection criteria, and deletion triggers — which is especially useful since there is no output schema. It does not discuss behavior for missing patterns or invalid cases, but the safety profile is well covered by 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 short sentences with no filler. It front-loads the concrete returned fields and ends with a practical use trigger. Every sentence earns its place.

  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 description usefully lists the returned evidence-plan elements, partially compensating for the missing output schema. However, given the highly nested case parameter and zero parameter semantics in the description, an agent may struggle to construct a valid request or understand invalid-input behavior.

  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, but it only says 'one pattern in one case.' It gives almost no guidance on how to populate the large nested case object or what values the pattern string should take. The rich schema structure for case is not reflected in the description.

  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 opens with a specific verb and resource: 'Return the hypothesis, measurements, experiment, rejection criteria, and deletion triggers for one pattern in one case.' This clearly scopes the tool to a single pattern and case, which distinguishes it from broader sibling tools like query_pattern_graph and plan_pattern_adoption.

  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 second sentence gives an explicit use condition: 'Use when a recommendation needs proof before implementation.' However, it does not name alternative tools or state when not to use this tool, so exclusion guidance is left implicit.

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

• compare_pattern_optionsA
  4.1/5.0
  Behavior4/5

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

  Annotations already cover the safety profile (readOnly=true, idempotent=true, non-destructive), so the description adds genuinely useful behavior beyond them: it discloses that the tool may deliberately return no winner when evidence is insufficient, and that its output states the forces that would make each option preferable. This is substantive behavioral context, not a restatement of annotations. No contradiction with 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 sentences with zero waste. The core action is front-loaded, and the second sentence adds the critical behavioral nuance about insufficient evidence and force-based output. Every clause earns its place.

  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 moderately complex (large nested case schema, no output schema), and the description covers the essential outcome behavior: when no winner is returned and what the output expresses (preferring forces). However, it does not describe the output structure of a comparison result or how the many case fields are weighted, which leaves an agent guessing about the return format and the comparison criteria.

  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 adds meaning by clarifying 'patterns' are named patterns limited to 2-6 (matching schema minItems/maxItems) and that 'case' is exactly one concrete case. However, the case object is large and heavily nested with 16+ subfields, and the description provides no guidance on which fields matter or how they feed the comparison. The schema's self-descriptive property names and enums carry most of the weight.

  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 verb and resource: 'Compare two to six named patterns against one concrete case.' The scope is precise and the action is clearly differentiated from sibling tools like detect_pattern_misuse (detection) and stress_test_pattern_decision (stress-testing a single decision). No ambiguity about what this tool does.

  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?

  Establishes a clear usage context: comparing a bounded set of patterns against a single concrete case. The 'two to six' constraint and 'one concrete case' framing distinguish it from sibling tools implicitly, though it does not explicitly name alternatives or state when NOT to use it.

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