Server Quality Checklist

Tool Scores

• adaptive_get_behavior_summaryA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description bears the full burden for behavioral disclosure. It begins with 'Returns' which implies a read-only operation, and it lists the types of data provided, but it does not explicitly state that it is side-effect-free, lack of required permissions, or any limitations. The metric list adds context, but key behavioral traits are left implicit.

  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 extremely concise: two sentences total. The first sentence states the core purpose, and the second lists specific metrics. No filler or redundant wording exists, and the structure front-loads the key information.

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

  Completeness4/5

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

  For a simple read-only tool with one optional parameter and no output schema, the description is fairly complete. It lists the main categories of returned data, giving the user a clear idea of what to expect. It could mention the format of the aggregates or the time window, but these are not essential given the tool's low 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?

  The input schema already provides a complete description for the only parameter (window_count, with default of 3), yielding 100% schema coverage. The description adds no additional explanation about the parameter's effect or usage, so it does not enhance the schema. A baseline of 3 is appropriate since the schema fully covers the parameter.

  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 function: it 'Returns recent behavior aggregates from the BehaviorTracker' and enumerates specific metrics like pane dwell times, command frequency, scroll metrics, alert response times, and takeover duration. This specific verb+resource pairs with an explicit list of outputs, distinguishing it from sibling tools such as adaptive_get_accuracy.

  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?

  There is no explicit guidance on when to use this tool versus alternatives. While the content implies it is appropriate for retrieving behavior summaries, it does not mention exclusions or mention sibling tools like adaptive_get_accuracy or adaptive_get_recommendation. No when-to-use/when-not-to-use context is provided.

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

• raxol_get_modelA
  3.6/5.0
  Behavior3/5

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

  With no annotations, the description must carry the burden. It discloses the return format ('inspected Elixir term') and the context ('headless Raxol session') but does not explicitly state side effects, read-only nature, or error behavior. For a simple getter, this is minimally adequate.

  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, front-loaded sentence with no redundant words. Every phrase adds value: the resource, the context, and the return format are all present.

  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 getter, the description covers the core: what is returned, the return format, and the session context. It does not mention potential error conditions or whether a session must already exist, but given the simplicity and full schema coverage, it is 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% and the parameter 'id' has a description ('Session identifier'). The tool description adds no additional parameter context, but the baseline of 3 applies when the schema fully documents parameters.

  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 'Returns' and a specific resource 'current TEA model (application state)', clearly distinguishing this tool from sibling tools like raxol_start and raxol_screenshot. The headless session qualifier adds precision.

  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 provided on when to use this tool versus alternatives. The description does not mention exclusions, prerequisites, or complementary tools, leaving the agent without context for selection.

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

• adaptive_accept_recommendationA
  3.8/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It adds context by noting that acceptance 'feeds positive signal into the feedback loop for model improvement,' but it does not disclose other potential side effects like reversibility, permissions, or response behavior. This is a moderate level of 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, front-loaded with the core action, and every sentence adds value. No fluff or redundant repetition of schema fields.

  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 tool with no annotations or output schema, the description explains the purpose and a key behavioral consequence (feedback loop). It is adequate for the tool's complexity, though it could mention prerequisites or return values. Overall, sufficiently complete but not exhaustive.

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

  Parameters3/5

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

  Schema description coverage is 100%, so the schema already fully documents 'recommendation_id.' The description adds identifying context ('pending layout recommendation') but does not go beyond the schema's parameter meaning. Baseline 3 applies because the schema 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 uses a specific verb ('Accepts') and resource ('pending layout recommendation by ID'). It clearly differentiates from sibling tools like adaptive_reject_recommendation by emphasizing the accept action and the feedback loop purpose.

  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 implies when to use this tool (for accepting a pending layout recommendation) but does not explicitly mention alternatives or when not to use it. The existence of adaptive_reject_recommendation as a sibling is not referenced, so usage guidance is only implied rather than explicitly contrasted.

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

• adaptive_reject_recommendationA
  3.8/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 full burden. It discloses a key side effect ('feeds negative signal into the feedback loop for model improvement'), which is helpful. However, it does not state whether the rejection is reversible, what happens to the recommendation afterward (e.g., removed, marked), or any permissions needed. It also implies the recommendation must be 'pending' but does not explicitly state the precondition.

  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 main action in the first sentence, and the second sentence provides useful additional context. There is no redundant or irrelevant information.

  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 tool is simple with one parameter and no output schema. The description covers what the tool does and the purpose (negative feedback loop). It is largely complete for an agent to use correctly, though it could mention what a successful rejection returns or any error conditions. However, given the simplicity, the description is sufficiently informative.

  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 schema description coverage is 100%, and the parameter description ('The recommendation ID to reject') fully explains the parameter. The tool description adds context that the ID refers to a 'pending layout recommendation,' which adds some meaning beyond just 'recommendation ID,' but it does not substantially enhance the parameter understanding.

  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 ('Rejects') and identifies the exact resource ('pending layout recommendation') and the identifier used ('by ID'). This clearly differentiates it from sibling tools, especially adaptive_accept_recommendation which is the opposite action.

  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 implies the usage context by stating the action ('Rejects a pending layout recommendation') but does not explicitly mention alternative tools or when to prefer this over adaptive_accept_recommendation or adaptive_get_recommendation. The when-to-use is clear from the action, but there are no explicit exclusions or comparisons.

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

• raxol_listA
  3.8/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 full responsibility for behavioral disclosure. It states the scope ('active headless') but omits any details about side effects, permissions, rate limits, or how 'active' is defined. The description essentially only repeats the function name's verb 'Lists' with minimal added context.

  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, front-loaded sentence with no unnecessary words. It clearly and efficiently communicates the tool's purpose.

  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 list tool with no parameters and no output schema, the description is largely complete. However, it does not mention what the return format will be or clarify the concept of 'active' sessions, which could be relevant context for an agent. This is a minor gap.

  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 coverage is trivially 100%. The description adds no parameter information, but none is needed. The baseline for 0 parameters is 4, and the description does not detract from that.

  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 'Lists' and identifies the resource as 'all active headless Raxol sessions'. This clearly distinguishes it from sibling tools like raxol_start and raxol_stop, which perform different actions.

  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 implies usage when you want to retrieve active headless sessions, but it does not explicitly state when to use this tool instead of alternatives, nor does it mention any exclusions or prerequisites. It provides no comparison with sibling tools.

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

• raxol_stopA
  3.8/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 the core side effect (stops session, frees resources) but does not mention idempotency, error behavior (e.g., if session already stopped), permissions, or whether the action is reversible. The mutation nature is clear, but additional context is missing.

  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 that is direct and front-loaded with the verb 'Stops'. It contains no redundant or filler 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 simple tool with one parameter and no output schema, the description adequately explains the tool's purpose and core side effect. However, it omits behavioral details like idempotency and error handling, which would make it fully 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% since the only parameter 'id' has a description ('Session identifier'). The tool description adds no extra meaning beyond the schema, so the baseline 3 applies.

  Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

  Purpose5/5

  Does the description clearly state what the tool does and how it differs from similar tools?

  The description uses a specific verb 'stops' and clearly identifies the resource ('running headless Raxol session') plus the side effect ('frees its resources'). This clearly distinguishes it from siblings like raxol_start and raxol_list.

  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 implies usage for terminating a session but provides no explicit guidance on when to use versus alternatives, when not to use, or prerequisites. The word 'running' suggests it only applies to active sessions but this is not made explicit.

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

• adaptive_get_accuracyA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It explains the output (a percentage) and the underlying logic (acceptance vs rejection), but it does not detail how the percentage is computed, whether it is session-based, or any other behavioral nuances. It is transparent at a basic level but not exhaustive.

  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, front-loaded with the primary purpose and immediately followed by a clarifying statement. Every word earns its place, with 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 no-parameter getter with no output schema, the description sufficiently explains what is returned and the metric's meaning. It does not specify when data is available or how to interpret extreme values, but those are minor gaps given the tool's simplicity. The presence of related sibling tools provides surrounding context.

  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 there is nothing for the description to clarify beyond the schema. According to the rule, a baseline of 4 is appropriate when no parameters exist. The description adds meaning by explaining what the output represents, but parameter semantics are not applicable.

  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 'Returns the feedback loop acceptance accuracy as a percentage.' This is a specific verb (returns) and resource (acceptance accuracy), and it distinctively differs from sibling tools like adaptive_accept_recommendation or adaptive_get_recommendation by focusing on the aggregate metric rather than individual actions or recommendations.

  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 implies the tool is used to check how often recommendations are accepted vs rejected, but it does not explicitly state when to use it or contrast it with alternatives. No exclusions or specific contexts are provided, making usage guidance merely implied rather than explicit.

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

• raxol_screenshotA
  4/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 of behavioral disclosure. It adds useful detail about the output format (plain text, no ANSI codes) and implies a read-only screenshot operation, but it does not explicitly state that the tool has no side effects or what happens if the session is invalid.

  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 concise sentences, front-loaded with the core action and followed by a key output detail. No filler or redundant phrasing.

  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 single-parameter tool with no output schema, the description covers the essential purpose and return format. It could mention error behavior or session prerequisites, but overall it is sufficient 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?

  The input schema already has 100% coverage for the single parameter 'id', with a clear description ('Session identifier'). The tool description adds no additional parameter detail beyond naming the session, so a 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 states a specific action ('Captures a text screenshot') and the resource ('a running headless Raxol session'), making the tool's purpose immediately clear. It distinguishes itself from sibling tools like raxol_stop or raxol_send_key by focusing on capturing screen content.

  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 context of use is clear: it applies to a running headless session and returns plain text. However, it does not explicitly mention when not to use it or name alternative tools, falling short of full usage guidance.

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

• raxol_send_keyA
  4.2/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 transparently discloses the supported input types (characters, special keys, modifiers) and the output behavior (returns updated screen content). It does not mention error handling or edge cases, but for a keystroke tool this is acceptable and adds meaningful behavioral context beyond just the schema.

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

  Conciseness5/5

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

  The description is compact and well-structured. It opens with the core action, lists supported key categories in a parenthetical, and provides three clear JSON examples. Every sentence contributes essential information without 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 tool with six parameters and no output schema, the description is reasonably complete. It explains what the tool does, what inputs are accepted, and that it returns 'updated screen content'. The absence of a detailed return format is a minor gap, but the examples and schema cover the essential usage context.

  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 input schema already provides 100% parameter coverage, so the baseline is 3. The description adds value by enumerating valid character and special key examples, showing modifier usage patterns, and clarifying that 'wait_ms' controls dispatch delay. The examples in the description reinforce and extend the schema definitions.

  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 action: 'Sends a keystroke to a headless Raxol session' and explicitly notes it returns updated screen content. This is a specific verb+resource pairing that distinguishes it from sibling tools like raxol_screenshot (which only captures screen) and raxol_start/stop (which manage sessions).

  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 implies usage when you need to send keyboard input to a Raxol session, supported by examples and key types. However, it does not explicitly state when to use this tool over alternatives (e.g., when to use raxol_screenshot instead) or any exclusions, leaving the guidance implicit rather than direct.

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

• raxol_startA
  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 burden of behavioral disclosure. It explicitly mentions headless mode, return value (session ID), and the accepted input forms (module or path). It does not detail error handling or lifecycle behavior, but the core behaviors are transparent enough for a start operation.

  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 concise, front-loaded with the main purpose, and includes well-chosen examples. Every sentence serves a purpose without redundancy. The structure—overview, acceptance criteria, return value, examples—makes it easy to scan.

  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 5 parameters and no output schema, the description covers the key context: session ID return, input options, and example configurations. It omits error behavior and session lifecycle, but the given information is sufficient for basic usage. More details on mutual exclusion enforcement could improve completeness.

  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 parameters are already well-documented. The description adds examples but introduces a minor inconsistency by calling the module an 'atom' while the schema specifies a string. It clarifies mutual exclusivity and defaults implicitly through examples, but does not add significant meaning beyond 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 clearly states the tool 'Starts a headless Raxol session' with a specific verb and resource. It distinguishes from siblings like raxol_stop or raxol_list by focusing on the initiation action. The provided examples further clarify the function's scope.

  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 implies when to use the tool (to start a session) and provides usage examples with module or path. It does not explicitly list exclusions or alternatives, but the naming and examples make the intended context clear. Slight gap in not stating when not to use (e.g., when a session already exists).

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

• adaptive_get_recommendationA
  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 of behavioral disclosure. It clearly states the return type, contents (layout changes, confidence, reasoning), and the null return when no recommendation exists. It does not disclose potential side effects, but the 'get' nature implies a read-only operation, and the description adds meaningful behavioral context beyond the tool name.

  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, each earning its place: the first states the primary purpose, the second lists the response contents, and the third covers the null case. It is front-loaded with the key action and avoids any 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 getter with no parameters and no output schema, the description fully explains the return value, including what is included (layout changes, confidence, reasoning) and the null condition. No additional context is needed for effective use, making it complete given the tool's simplicity.

  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 schema requires no additional description. The description inherently provides all needed parameter context (i.e., none). Per the baseline for 0 parameters, a score of 4 is appropriate since no parameter explanations are necessary.

  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 ('returns') and identifies a clear resource ('most recent layout recommendation from the adaptive UI system'). It also distinguishes the tool from siblings by specifying its content (layout changes, confidence, reasoning), which sets it apart from tools like adaptive_get_accuracy or adaptive_reject_recommendation.

  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 implies the tool is for retrieving the latest recommendation, but it doesn't explicitly state when to use it compared to alternatives like adaptive_accept_recommendation or adaptive_reject_recommendation. There is no mention of prerequisites, exclusions, or a 'use this when' context, so guidance is only implied rather than explicit.

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