Server Quality Checklist

Tool Scores

• typeC
  2.7/5.0
  Behavior2/5

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

  With no annotations provided, the description bears full responsibility for behavioral disclosure. It states the action ('set the text value') but omits relevant side effects such as whether it replaces the entire existing value, requires focus, or errors when the selector isn't found. The minimal disclosure is insufficient for a mutation tool.

  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 a single, focused sentence with no filler. It front-loads the core action and matching criterion. While it might be considered under-specified, it is appropriately concise for a simple tool.

  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?

  For a tool with 3 parameters, no output schema, and no annotations, the description is too sparse. It doesn't clarify the optional 'window' parameter, behavior on selector miss, or how the text is applied (replace vs append). The agent lacks critical details for reliable invocation.

  Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

  Parameters2/5

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

  Schema coverage is only 33% (only 'selector' has a description). The description does not explain the 'text' parameter (required) or the optional 'window' parameter, and its mention of 'field matched by selector' only hints at the selector role. With low schema coverage, the description should compensate but doesn't.

  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 ('set') and resource ('text value of a field') with a clear matching mechanism ('by selector'). It is distinct from siblings like 'click' or 'invoke_action' because it explicitly targets text input, though it doesn't name an alternative to disambiguate.

  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?

  No guidance is given on when to use this tool versus alternatives like 'click' or 'invoke_action'. There is no mention of prerequisites (e.g., field must be visible/focused) or exclusionary conditions, leaving the agent to infer applicability from the name and description alone.

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

• invoke_actionC
  2.9/5.0
  Behavior2/5

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

  With no annotations provided, the description must carry the full burden of disclosing side effects. It implies a mutation ('Trigger') but doesn't state whether it changes application state, is synchronous, requires specific permissions, or handles errors. The reference to registration is a hint but insufficient for an agent to predict consequences.

  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 directly states the core function without any extraneous words. The verb 'Trigger' and resource 'action hook' are placed upfront, making it maximally concise while retaining clarity.

  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?

  For a simple 1-parameter tool with no output schema, the description is minimal. It lacks information about return values, error behavior, timing (synchronous vs async), and when it is appropriate to invoke. The absence of context about action availability and side effects leaves an agent under-equipped to integrate this tool correctly into a workflow.

  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 description adds meaning to the single 'name' parameter by explaining it as the name of a registered action hook, which goes beyond the bare string type in the schema. However, it doesn't specify allowed values, format, or how to discover valid names. Given 0% schema coverage and one parameter, the description provides some compensation but not complete clarity.

  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 triggers a named action hook, with the verb 'Trigger' and resource 'action hook', and references the registration API via AppMCP.registerAction. It is distinguishable from sibling tools like click or get_ui_tree, but it doesn't explicitly contrast with them, so it falls 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 Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like click, type, or wait_for. It doesn't mention prerequisites, conditions, or when an action hook should be preferred over direct UI interactions. This is a clear gap in usability.

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

• clickB
  3.1/5.0
  Behavior2/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It reveals matching semantics via the selector grammar, which is useful, but says nothing about success/failure behavior, what happens when the selector matches nothing or multiple views, whether the call blocks until the view is ready, or side effects. These gaps are significant for a zero-annotation interaction 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 terse sentences with zero waste. The matching grammar is front-loaded immediately after the core action, so the most decision-relevant information is visible first. Every word 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?

  For an interaction tool, the description omits key operational details: what happens on a failed or ambiguous selector match, whether a wait is needed before clicking (relevant given the sibling wait_for), and any timeout or blocking behavior. No output schema exists to compensate, so an agent has limited ability to predict outcomes.

  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?

  Schema coverage is only 50% (selector has an example, window has no description), so the description should compensate. It does well for selector by documenting the full grammar '#id' | Role 'Label' | 'Label' | Role, going beyond the schema's single example. However, the window parameter remains undocumented in both the schema and description.

  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?

  Clear verb+resource: 'Tap a view matched by selector' states precisely what the tool does. The selector grammar line adds specificity. It distinguishes from siblings like screenshot, type, and wait_for by their obvious functions, but does not differentiate from invoke_action, which could overlap in purpose.

  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?

  No guidance on when to use this tool versus alternatives. There is no mention of prerequisites (e.g., needing wait_for to ensure the view exists before clicking), no exclusions, and no mention of how to choose between click and invoke_action. The agent must infer usage entirely.

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

• wait_forB
  3.3/5.0
  Behavior3/5

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

  No annotations are provided, so the description must carry the full burden. It discloses the polling behavior and timeout, which is useful. However, it does not specify what happens on timeout (error vs. return value), whether it blocks, or whether it returns the matching element. These gaps are significant for a polling 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?

  The description is a single sentence with no extraneous words. It is front-loaded with the core action and condition, making it immediately scannable. There is zero redundancy.

  Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

  Completeness2/5

  Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

  With four parameters, no output schema, and no annotations, the description leaves critical gaps: return value, timeout behavior, selector semantics, and window usage. The tool is not fully usable without additional documentation or inspection of the schema, which is only partial.

  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?

  The schema only describes pollMs and timeoutMs with defaults (50% coverage), leaving selector and window unexplained. The description's phrase 'until a selector appears' hints at selector's role but does not clarify its format (e.g., CSS vs. XPath) or the window parameter's purpose. Since the required parameter selector is undocumented, the tool is hard to call correctly.

  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 verb ('Poll') and resource ('UI tree') with a clear condition ('until a selector appears, or time out'). It distinguishes itself from siblings like get_ui_tree (which retrieves immediately) and click/type (which act on elements), making the 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 Guidelines2/5

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

  The description gives no guidance on when to use this tool versus alternatives. It does not mention prerequisites (e.g., a window must be active) nor does it contrast with get_ui_tree or polling approaches. An agent must infer that it's for waiting on UI elements, but the description never explicitly states when it should be chosen over others.

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

• get_ui_treeA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description is the only source of behavioral information. It implies a read-only operation (dump) but never explicitly states that it does not modify the UI or that it requires no special permissions. It also does not disclose potential performance implications or error behavior. The description is not misleading, but it leaves room for clarification.

  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 redundancy. The main purpose is front-loaded, and the compact option is mentioned as a secondary note. Every clause adds information, and the structure is efficient.

  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?

  Since there is no output schema, the description adequately describes the return content (roles, labels, values, state, frames, stable ids). It does not mention error cases (e.g., invalid window) or what happens if the window is unavailable, but for a read-only inspection tool this is a reasonable level of completeness. The main missing piece is explicit guidance on when to use this tool, which is already penalized under usage guidelines.

  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?

  Both parameters are fully documented in the schema with 100% coverage. The description only reiterates the effect of 'compact' ('terse outline') which matches the schema description. It adds no additional semantic value beyond what the schema already conveys, 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 clearly states the tool dumps the semantic view tree of a window as JSON, enumerating specific attributes (roles, labels, values, state, frames, stable ids). It is distinct from siblings like screenshot or click, since it focuses on reading the UI structure. The verb 'dump' is specific and the resource 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 Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives such as list_windows or screenshot. It only mentions the 'compact' parameter for a terser output, but does not explain scenarios where the tree is preferable or how it relates to other inspection tools. This is a clear gap.

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

• list_windowsA
  3.9/5.0
  Behavior3/5

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

  No annotations are present, so the description carries the burden of behavioral disclosure. It states it lists windows and names the fields, but does not explicitly state it is read-only or has no side effects. While 'list' strongly implies a non-mutating operation, the absence of any annotation or explicit safety note leaves a small gap. Still, the behavior is clear enough for a simple read 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?

  A single, tightly written sentence delivers all essential information: the action, the resource, and the payload fields. No filler words or redundant phrases. The parenthetical enumerating fields is efficient and front-loaded.

  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 parameterless listing tool, the description is complete. It tells the agent what the tool does and what data it returns (id, title, key, frame). There is no output schema, so the field list is the only contract, and that is provided. No other contextual details (like ordering, frequency, or limitations) seem necessary for correct invocation.

  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 schema coverage is trivially 100%. There is nothing to add about parameter meaning. The description's mention of return fields (id, title, key, frame) gives agents a concrete idea of what to expect, though it doesn't describe how these fields are formatted or whether they correspond to parameter-like filters. Baseline for 0 params is 4.

  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 ('List'), identifies the resource ('the app's on-screen windows'), and enumerates the returned fields (id, title, key, frame). It clearly distinguishes from siblings like get_ui_tree (UI hierarchy) and screenshot (image capture), making the tool's 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 Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives. For example, it doesn't state that this should be used to enumerate open windows before interacting with them, nor does it mention any exclusions (e.g., 'use get_ui_tree for widget-level details'). An agent is left to infer usage context from the tool name and sibling list.

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

• screenshotA
  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 full behavioral disclosure burden. It explicitly notes 'Rendered in-process by the app — no Screen Recording permission', which is valuable permission/auth context. It also clarifies the scope (whole window or single node). It doesn't mention side effects, but the action is read-only and the description implies no data mutation.

  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 with zero filler. The primary action and output are stated first, followed by the important permission detail. Every word adds 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 tool with two optional parameters and a straightforward output (PNG), the description provides sufficient information for correct invocation. It doesn't specify the exact return format (e.g., file path vs binary data), but 'to PNG' strongly implies the output is an image. Given no output schema, a brief note on return format would improve completeness slightly, but it's not a critical gap.

  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 parameters are fully documented in the schema. The description adds minimal extra meaning beyond restating the selector concept ('via `selector`') which is already in the schema. The baseline of 3 applies since the schema fully covers 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 uses a specific verb ('Render') with a clear resource ('a window or a single node') and output format ('PNG'). It clearly differentiates from siblings like get_ui_tree (which retrieves structure) and click/type (which perform actions) — this is the only tool that captures visual output.

  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 purpose is self-evident: when an agent needs a visual representation of a window or node, this tool is the obvious choice. No alternative is mentioned, but given the sibling list, no other tool does this. It doesn't provide explicit when-not-to-use guidance, but the context is clear enough.

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