Server Quality Checklist

Tool Scores

• get_promptA
  4/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 behavioral disclosure burden. It reveals the non-obvious fallback behavior and the input sources ('flow.md and ranked locators'). It could be more explicit about whether synthesis has side effects or writes files, but the main conditional behavior is 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?

  One well-structured sentence with the primary behavior front-loaded and the fallback appended after a semicolon. Every phrase earns its place, and there is no repeated or irrelevant 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?

  For a two-parameter tool with no output schema, the description explains its returned output and fallback behavior well. It could slightly strengthen completeness by stating the return format, but the low tool complexity and clear sources make it largely complete.

  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%, so both 'session' and 'framework' are already documented structurally. The description independently references session behavior and prompt synthesis sources but does not add new parameter-level meaning beyond what the schema provides. 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 uses a specific verb and resource: it returns PROMPT.md if present, and otherwise synthesizes a test-generation prompt. This clearly distinguishes the tool from siblings like list_sessions and read_session by positioning it as the session-prompt provider.

  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 makes its internal branch explicit: PROMPT.md is returned if present, otherwise a prompt is synthesized. However, it does not explicitly say when to choose this tool over list_sessions, read_session, or map_locator, so sibling routing is left to inference.

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

• map_locatorA
  4/5.0
  Behavior3/5

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

  There are no annotations, so the description carries the behavioral burden. It discloses meaningful constraints: Sauce Demo data-test ids still emit getByTestId, and testid is never mapped to getByRole('generic'). However, the result format is only vaguely described as 'snippet with score and stability', leaving the return structure and score semantics underspecified.

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

  Conciseness5/5

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

  The description is only two sentences, with the core purpose in the first sentence and a high-value edge-case constraint in the second. Every sentence earns its place, and there is no 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 a small schema and no output schema, the description covers the action, the input domain, the target frameworks, and a meaningful mapping exception. It could have clarified the output structure and the meaning of stability, but it is complete enough for an agent to call the tool confidently.

  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 covers all parameters with descriptions, so this is a baseline-3 case. The description re-emphasizes the {by, value} pair and framework context but adds no new semantic detail beyond what the schema provides.

  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, 'Map', and clearly identifies the resource: a PageSnap YAML locator converted into a Playwright, Selenium, or Cypress snippet. It also explains what the result contains — code, score, and stability. This clearly distinguishes the tool from the sibling tools, which are session-management operations.

  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 intended use case is explicit: convert a PageSnap YAML locator into framework-specific code. It does not enumerate alternative tools or when-not-to-use conditions, but given that the siblings are list_sessions, read_session, and get_prompt, the usage boundary is effectively clear.

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

• read_sessionA
  4/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 burden, and it does well:it discloses the truncation cap (200), the token-efficient ordering behavior ('keys/summary first'), and a deliberate exclusion ('does not dump YAML file bodies'). It does not cover failure behavior or the exact structure of keys/summary, so it stops just short of perfect.

  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 crisp sentences with zero filler. The first sentence states what is read; the second conveys caps, scope, and efficiency behavior. Everything included earns its place, and there is no redundancy.

  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 one-parameter read tool with no output schema, the description is nearly complete:it covers what is read, what is excluded, and a behavior limit. Minor gaps remain around what the returned keys/summary actually look like and how the cap 200 manifests, but these are relatively minor for invocation purposes.

  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?

  Input schema coverage is 100%:the only parameter, session, is well documented as either a folder name under PAGESNAP_SESSIONS_DIR or an absolute session path. The description doesn't add new parameter details, 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?

  Clearly specifies a verb ('Read'), a resource ('one PageSnap session'), and the contents returned: flow.md, YAML file names, and parsed controls capped at 200. The description naturally distinguishes the tool from list_sessions (list vs read) and from get_prompt/map_locator, which serve different purposes.

  Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

  Usage Guidelines3/5

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

  The intended use is implied: read a single session when you need its flow.md, YAML names, or parsed controls. However, the description does not explicitly state when to choose this over list_sessions, get_prompt, or map_locator, nor does it give exclusions.

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

• list_sessionsA
  4.7/5.0
  Behavior5/5

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

  With no annotations present, the description carries the full behaviorful burden and does well: it discloses the source directory, the exact summary fields returned, the fact that it is summary-only, and that it does not capture or open a browser. This gives an agent a reliable behavioral model.

  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, front-loaded with the main action, followed by output contents and the key exclusion. Every clause adds information and there is no waste.

  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 no-parameter, no-output-schema listing app, the description covers evocation, input location, output fields, and side-effect exclusion. It as nothing important to the caller or agent needs to correctly invoke and interpret the tool.

  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, so the base-4 for no-parameter tools applies. The description repeats no parameter information and instead focuses on behavior, which is appropriate since there is nothing to clarify about the input 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 clearly identifies the operation (list), the resource (PageSnap session packs), and the location (PAGESNAP_SESSIONS_DIR, default ./sessions). It also disambiguates the tool from browser-capture or open tools by explicitly stating it does not capture or open a browser.

  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 anks clear context for when this list-style tool is appropriate, including that it returns only summary fields and does not interact with a browser. It does not explicitly mention alternatives such as read_session, but the summary-only scoping makes the intended use clear.

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