Server Quality Checklist

Tool Scores

• get_tag_run_ruleC
  2.9/5.0
  Behavior2/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 says 'Return the rule' implying a read-only operation, but it does not disclose side effects, permissions, or return structure. The second sentence embeds instructions to call other tools, which is confusingly mixed into the tool's behavior description, potentially misleading about what the tool actually does.

  Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

  Conciseness3/5

  Is the description appropriately sized, front-loaded, and free of redundancy?

  The description is relatively short and front-loaded with 'Return the rule', but the second sentence is a run-on that mixes rule definition with imperative workflow instructions. It could be split into separate concerns: one sentence for what the tool returns, and another for contextual usage guidance if needed. Some content feels tangential to the tool itself.

  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?

  Given the tool has no parameters and no output schema, the description must clarify what the rule is and how to use it. It explains the trigger conditions but does not specify the return value's format or how to interpret it. The embedded instruction to call other tools suggests the description is trying to define a workflow rather than describe this tool's invocation, leaving the agent uncertain about what to do with the returned rule.

  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?

  The tool has zero parameters and the schema is empty with 100% coverage. The description adds no parameter details, but the baseline for 0-parameter tools is 4, as there is no parameter information burden. The description focuses on the tool's purpose rather than parameter formatting.

  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 starts with 'Return the rule', clearly indicating the tool returns some rule content, and the content is about tag-triggered MCP runs. This distinguishes it from sibling tools like analyze_and_fix_selector or run_test_and_analyze_failure. However, it doesn't specify the return format or whether it's a string, object, or instruction set, leaving 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?

  The description does not state when to use this tool versus alternatives. Instead, it instructs the agent to call run_test_and_analyze_failure first and then analyze_and_fix_selector on failure, which is guidance for a workflow involving other tools, not for selecting get_tag_run_rule. No exclusions or alternatives are mentioned.

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

• analyze_and_fix_selectorA
  3.9/5.0
  Behavior3/5

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

  With no annotations, the description carries the transparency burden. It discloses a prerequisite (read full spec), inputs to use, and that the fix should prefer getByRole. However, it does not state whether the tool modifies files (though 'suggest' implies non-mutating), how the fix is returned, or limitations on multiple failures.

  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, dense sentence that front-loads the purpose. Every phrase serves a function: 'Analyze Playwright failure' states the task, 'require reading the full spec for context first' gives a prerequisite, and the rest specifies inputs and output preference. No wasted words.

  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 6 parameters, no output schema, and no annotations, the description covers the primary workflow but leaves gaps: it doesn't explain the return format, how originalCode/failureContext should be used, or what constitutes a stable locator beyond getByRole. It is adequate for a simple analysis tool but not fully comprehensive.

  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 all six parameters are already described. The description adds minimal parameter-level guidance, only highlighting errorMessage, screenshotPath, and domSnapshot. It does not add semantics beyond the schema, so 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 states the tool's purpose: 'Analyze Playwright failure' and 'suggest a stable locator fix'. It distinguishes from siblings by focusing on analysis and fix suggestion, whereas tools like get_playwright_fix_workflow provide workflow guidance and run_test_and_analyze_failure executes tests.

  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 context: 'require reading the full spec for context first' and tells the agent to use 'error message + screenshot path (and optional DOM snapshot)'. It does not explicitly mention when not to use this tool or alternatives, but the workflow is clear enough.

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

• read_spec_fileA
  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 discloses that the tool auto-resolves imported page objects and provides complete deterministic context, which is useful behavioral information. However, it does not mention potential failure modes, whether it is strictly read-only, or any side effects, leaving some gaps.

  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, front-loaded with the action verb 'Read,' and every sentence adds value. It efficiently conveys purpose, output, and usage priority without unnecessary 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 tool's simplicity (one parameter, no output schema, no annotations), the description provides sufficient context about what it does and why it matters. It names the return context (step flow, DSL calls, selectors) and its role in the workflow, though it could mention error handling or what happens if the file is missing.

  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% for the single parameter specFilePath, which is already described as 'Absolute path to the spec file'. The description adds no additional meaning to the parameter, so the baseline score 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 clearly states the tool reads a spec file and auto-resolves its imported page object, naming specific content (full step flow, helper DSL calls, selector definitions). It distinguishes itself from siblings like analyze_and_fix_selector by positioning this as the prerequisite step.

  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 says to call this tool before analyze_and_fix_selector and instructs 'Never let the model guess about test intent; call this first,' giving clear when-to-use guidance. It does not mention alternatives or when not to use it, but the primary use case is unambiguous.

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

• get_internal_locator_rulesA
  4.2/5.0
  Behavior3/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 that the tool returns rules and adds the behavioral detail that the rules prefer getByRole and disallow XPath. However, it does not specify the return format (e.g., list, object) or whether any read-only guarantees exist, leaving some ambiguity for a zero-parameter getter.

  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, crisp sentence that front-loads the verb 'Return' and packs key details into a parenthetical. Every word contributes value, and there is 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?

  For a simple getter with no parameters and no output schema, the description provides enough context about the tool's purpose and the nature of the returned rules. It could mention the return structure or that the rules are static, but the tool's simplicity makes 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.

  Parameters4/5

  Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

  The tool has zero parameters, and the schema confirms this with an empty properties object. The baseline for zero parameters is 4, and the description adds no unnecessary parameter details, so the score reflects that the schema fully covers the parameter aspect.

  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 that the tool returns company internal Playwright locator rules, and specifies the content preference (getByRole preferred, no XPath). This distinguishes it from sibling tools that handle rule evolution, tag rules, or workflow fixes, so the purpose is unambiguous.

  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 conveys a clear use case: retrieve internal Playwright locator rules. It does not explicitly mention when not to use it or name alternatives, but the context of 'internal' and the sibling tool names provide enough situational clarity for an agent to decide when this tool is appropriate.

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

• resolve_spec_by_tagA
  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 transparency burden. It discloses that the tool scans test specs, returns an absolute path, and is deterministic. While it doesn't explicitly state side effects or failure behavior, the nature of 'resolve' and 'scanning' implies a read-only operation. This is sufficient for a resolver tool.

  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. The first sentence states the action, the second provides workflow context and rationale. Every word earns its place, and the most critical 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?

  The description covers the tool's purpose, its position in the workflow, and the deterministic nature of the result. It also implies the return value (absolute path). Missing edge-case behavior (e.g., what happens if the tag is not found) but for a simple resolver, this is adequate.

  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 input schema covers all three parameters with descriptions (100% coverage), so baseline is 3. The description adds no additional parameter-specific meaning beyond the overall scanning behavior and references the @AUT-xxx tag format, which is already in the 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?

  The description uses a specific verb and resource 'Resolve the absolute spec file path that contains a given @AUT-xxx tag', clearly distinguishing it from siblings like read_spec_file (which reads the file content). It also highlights the intended workflow, making the tool's unique role obvious.

  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 the workflow: use this tool first to find the spec, then call read_spec_file. 'Avoid guessing which spec to read' gives clear when-to-use context. It doesn't list alternative tools or when not to use it, but the context is strong enough for an agent to infer appropriate usage.

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

• run_test_and_analyze_failureA
  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 that the tool executes an npx playwright command, returns passed/failed status, resolvedContext (with enumerated values), artifacts, and enforces a retry stop-loss policy. This adds valuable behavioral context beyond the schema. It does not mention side effects or environment dependencies, but these are less critical for a test runner.

  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, front-loaded with the command, then outputs, then retry policy. Every sentence conveys essential information without redundancy. It is concise and well-structured, making it easy for an agent to quickly grasp the tool's function.

  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 tool with no output schema, the description identifies the primary outputs (passed/failed, resolvedContext with allowed values, artifacts, shouldStop) and references the downstream consumer (analyze_and_fix_selector). It covers the core usage scenario and termination condition. It could be more complete by describing the artifact format or error handling, but it is sufficient for an agent to invoke and interpret results.

  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 input schema already provides full descriptions for all three parameters (tag, projectRoot, attemptNumber), so the baseline is 3. The description adds minor context by illustrating the grep usage (@<tag>) and explaining the retry stop-loss behavior for attemptNumber, but this largely overlaps with schema descriptions. No significant new parameter semantics are introduced.

  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 action ('Run npx playwright test --grep @<tag>'), the resource (a Playwright test tagged with the provided tag), and the purpose (collect failure artifacts for analyze_and_fix_selector). It distinguishes this tool from siblings like get_failure_artifacts by emphasizing that it actually executes the test, not just retrieves artifacts.

  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 clear context: use this tool to run a tagged test and obtain failure artifacts for downstream analysis. It also provides an explicit stopping condition (shouldStop at attemptNumber >= 3) with human escalation. However, it does not explicitly contrast with alternative sibling tools (e.g., get_failure_artifacts) or specify when not to use this tool, so it lacks explicit exclusions.

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

• read_page_object_selectorsA
  4.3/5.0
  Behavior4/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 success output format and the fallback behavior when structured extraction fails. It does not mention error cases beyond the fallback, but for a read-only extraction tool this is substantial transparency.

  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, both information-dense. The first states the action and outcome, the second adds purpose and fallback. No redundant wording or filler.

  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 simple one-parameter read tool with no output schema, the description is complete: it states what is extracted, the mapping format, the purpose, and the fallback if extraction fails. Nothing essential is missing.

  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% for the single parameter, pageObjectPath, which is fully described as an absolute path. The description adds no additional parameter-specific information beyond the schema, so the baseline 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?

  The description clearly states the tool extracts all selector definitions from a page object file, with a specific verb and resource. It also describes the output mapping, distinguishing it from sibling tools like analyze_and_fix_selector by focusing on reading rather than modifying.

  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 clear context for when to use this tool: 'essential for diagnosing broken selectors without guessing.' It does not explicitly name alternatives or exclusions, but the read-only nature and diagnostic purpose imply when it is appropriate.

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

• propose_rule_evolutionA
  4.4/5.0
  Behavior5/5

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

  With no annotations, the description fully discloses key behavioral traits: it writes to a PENDING queue, does not modify .cursor/rules files, and requires human APPROVAL before application. This gives the agent a clear safety profile and workflow understanding.

  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?

  Four sentences, each earning its place: purpose, write target, approval requirement, and governance summary. Information is front-loaded and there's zero waste.

  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 description covers the core behavior and workflow adequately. It doesn't explain return values or file naming, but given no output schema and 100% parameter coverage, the essential context is present. A minor gap is not specifying what the tool returns on success or whether it errors on duplicate proposals.

  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 parameters are already well-documented. The description does not add parameter-specific details, but it provides useful workflow context (e.g., 'learned pattern', 'PENDING queue') that reinforces the purpose. 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 states exactly what the tool does: propose a learned pattern as a new rule entry after a test passes following an automated fix. It distinguishes from siblings by emphasizing it writes to a PENDING queue and does NOT modify rules files directly, clarifying its governance 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?

  It gives a clear trigger condition ('after a test passes following an automated fix') and contrasts with direct file modification. It doesn't explicitly name alternative tools like validate_and_apply_fix, but the governance framing makes when to use it unambiguous.

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

• validate_and_apply_fixA
  4.4/5.0
  Behavior4/5

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

  With no annotations, the description carries full responsibility for behavioral disclosure. It discloses the validation rules (no XPath, no bare CSS classes, iframe must use frame.locator), the application step, and the violation-return/retry behavior. It also explains enforcement consequences vs direct edits. However, it does not specify whether partial application occurs or the exact state of the file after a violation, which would improve transparency.

  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 long and front-loaded with the core purpose. Every sentence earns its place: the first defines the action, the second covers return/retry behavior, and the third emphasizes enforcement. No redundant wording.

  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 tool with no output schema and no annotations, this description gives a solid contract: validation rules, application, violation return, and retry directive. It could be more explicit about failure atomicity (whether any changes are applied when violations occur), but overall it is complete enough for an agent to invoke 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 each parameter having a meaningful description. The tool description adds context about validation rules but does not provide additional detail on individual parameters beyond the schema. Baseline 3 is appropriate since the schema already does the heavy lifting.

  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 validates proposed code changes against LOCATOR_VIOLATION_RULES and then applies them to a spec file. It distinguishes itself from sibling read/analysis tools by explicitly stating it is the only valid path to write spec changes, making its unique purpose unambiguous.

  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 says 'This is the only valid path to write spec changes; direct file edits bypass LOCATOR_RULES enforcement,' providing a strong directive on when to use this tool. It also instructs the agent to fix and retry if violations are returned, covering the expected follow-up workflow.

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

• get_failure_artifactsA
  4.5/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. It discloses that the tool scans the test-results directory and returns deterministic artifact locations, and it implies the output fields ('screenshotPath + tracePath') via the instruction to pass them into the analyzer. This is sufficient for a read-only search tool. It does not mention error behavior when no artifacts are found, but that is a minor 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?

  The description is just two sentences. The first states the action and outputs, the second provides a deterministic guarantee and the next step. Every sentence contributes essential information with no redundancy or filler.

  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 simple tool with no output schema and only two optional parameters, the description tells the model what it returns (screenshot path, trace.zip), how it behaves (deterministic), and what to do next (pass into analyze_and_fix_selector). It is well-integrated into the workflow and covers the essential context for correct invocation. Missing artifact handling is not critical given the tool's simplicity.

  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 input schema already includes full descriptions for both parameters (tag and projectRoot), achieving 100% schema description coverage. The description adds little beyond the schema; it does not explain how tag or projectRoot affect the scan. The example value 'AUT-589-1' is in the schema, not the description. Thus, 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?

  The description uses the specific verb 'Scan' and clearly identifies both the target resource ('test-results directory') and the output artifacts ('latest screenshot path, trace.zip path'). It distinguishes itself from the sibling tool 'analyze_and_fix_selector' by positioning itself as the retrieval step, making its purpose precise and unambiguous.

  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 instructs the model to 'pass screenshotPath + tracePath into analyze_and_fix_selector', giving a clear next step and the condition for use (whenever failure artifacts are needed). It also explains the benefit ('deterministic artifact location so the model never guesses'), which clarifies why this tool should be used instead of guessing paths. While it doesn't list negative conditions, the directive is strong and actionable.

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

• get_playwright_fix_workflowA
  4.5/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 fully discloses what the tool returns (the two-step workflow) and implies no side effects or additional behavior. There are no hidden mutations, auth requirements, or rate limits to disclose, making it adequately transparent.

  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 with a numbered list of two steps. It is front-loaded with the purpose and does not waste words. Every element earns its place, making it highly concise 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?

  For a simple zero-parameter tool with no output schema, the description is complete. It specifies exactly what the tool returns and the context in which it applies. The information is sufficient for an agent to select and invoke the tool correctly without any ambiguity.

  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?

  The tool has zero parameters, and the schema confirms this with an empty properties object. Per the baseline for 0-parameter tools, a score of 4 is appropriate since there are no parameter semantics to clarify.

  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 'Return' and the specific resource: 'the recommended workflow when fixing Playwright tests'. It provides the actual workflow steps, making the tool's purpose unmistakable and distinct from siblings like 'analyze_and_fix_selector' or 'get_failure_artifacts'.

  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: use this tool when fixing Playwright tests to obtain the recommended workflow. It does not explicitly mention alternatives, but the context is sufficient for a zero-parameter informational tool. The workflow steps imply it should be consulted before applying fixes.

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

• get_iframe_contextA
  4.7/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 of behavioral disclosure. It clearly states what the tool returns ('iframe locator string, count of frame operations, and enforcement reminder') and emphasizes the deterministic nature of the result. It does not mention error handling or side effects, but for a read-only extraction tool, the disclosed behavior is sufficient.

  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 long, front-loaded with the core action, and every sentence adds essential information. There is no filler or repetition of schema details, making it highly concise 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?

  Given a single parameter and no output schema, the description is complete: it explains what the tool does, what it returns, and exactly when to invoke it. It also integrates well with sibling tools by directing the calling sequence, leaving no critical gaps for an agent to guess.

  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?

  The schema describes specFilePath as 'Absolute path to the spec file' (100% coverage). The description adds meaning by noting the tool also reads 'its page object' and returns specific frame-related context, which goes beyond the raw parameter definition and helps the agent understand the tool's broader operation.

  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 ('Extract') and resource ('iframe selector and frame-related operations'), clearly distinguishing it from sibling tools like analyze_and_fix_selector or read_spec_file. It also states the source (spec file and page object), making the tool's function unambiguous.

  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 the tool: 'Call this for any failure whose context is ''iframe''' and positions it as a prerequisite before analyze_and_fix_selector. It also provides a strong exclusion rule: 'the model must never guess the iframe selector,' making the usage guidance direct and actionable.

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