Server Quality Checklist

Tool Scores

• btt_execute_triggerB
  3/5.0
  Behavior3/5

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

  Annotations provide substantial behavioral information (readOnlyHint=false, openWorldHint=true, idempotentHint=false, destructiveHint=false), so the description's burden is reduced. The description adds some context about executing 'all actions assigned to a trigger' and mentions the return value, but doesn't provide additional behavioral details like error conditions, side effects, or performance characteristics beyond what annotations already cover.

  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 efficiently structured with three clear sections: purpose statement, args explanation, and returns statement. Each sentence serves a distinct purpose with minimal waste. The formatting with clear section headers enhances readability without unnecessary verbosity.

  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 the tool's complexity (mutation operation with connection configuration), the description is incomplete. While annotations provide safety information and an output schema exists, the description fails to document critical connection parameters and provides no guidance on tool selection among similar siblings. For a tool that requires network configuration and authentication, more context would be helpful.

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

  Parameters2/5

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

  With 0% schema description coverage, the description carries full responsibility for parameter documentation. It only mentions that 'params' contains 'the UUID of the trigger to execute,' completely omitting the complex 'connection' configuration object with host, port, shared_secret, and use_cli parameters that are critical for tool operation. This leaves most parameters undocumented.

  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 action ('Execute all actions assigned to a specific trigger') and identifies the resource ('by UUID'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'btt_trigger_action' or 'btt_trigger_named', which appear to have overlapping functionality.

  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. With multiple trigger-related siblings (btt_trigger_action, btt_trigger_named, btt_get_trigger, btt_update_trigger), there's no indication of when this specific UUID-based execution approach is appropriate versus other trigger invocation methods.

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

• btt_import_presetB
  3/5.0
  Behavior3/5

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

  Annotations indicate this is a non-readOnly, non-destructive operation, which the description's 'Import' action aligns with (importing is typically additive). However, the description adds minimal behavioral context beyond this—it doesn't specify if the import overwrites existing presets, requires authentication via the connection config, or has side effects like triggering notifications. With annotations covering basic safety, the description provides some value but lacks depth.

  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 brief and front-loaded with the core purpose, followed by Args and Returns sections. However, the Args section is misleadingly simplified (referring to 'params' as just a path), and the Returns section is vague ('Confirmation of import'). It's efficient but could be more precise.

  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 the tool has annotations (covering readOnly/destructive hints) and an output schema (implied by 'Has output schema: true'), the description doesn't need to detail safety or return values. However, it's incomplete for a tool with 1 parameter that has 0% schema coverage and nested complexity—it should better explain the parameter structure and usage context to compensate.

  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 description coverage is 0%, meaning parameters are undocumented in the schema. The description only mentions 'Path to the preset file' for 'params', but 'params' is a nested object with 'path' and 'connection' sub-properties per the schema. It fails to explain the 'connection' configuration or its defaults, leaving key semantics unclear and not compensating for the schema gap.

  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 action ('Import') and resource ('BTT preset from a file'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'btt_export_preset' beyond the obvious import/export distinction, nor does it specify what a 'BTT preset' entails in this context.

  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. It doesn't mention prerequisites (e.g., needing a valid preset file format or BTT connection), when not to use it, or how it relates to sibling tools like 'btt_get_preset_details' or 'btt_export_preset' for preset management workflows.

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

• btt_display_notificationB
  3.2/5.0
  Behavior3/5

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

  Annotations indicate this is a non-destructive, non-idempotent, open-world operation. The description adds that it 'Displays a macOS notification' and returns 'Confirmation of notification being displayed,' which clarifies the action and output. However, it doesn't mention behavioral aspects like potential failures (e.g., if BTT isn't running), side effects (e.g., user interaction), or rate limits, leaving gaps despite annotations.

  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 brief and structured into three clear parts: purpose, args, and returns. It uses bullet-like formatting for parameters. However, the 'Args' and 'Returns' sections are somewhat redundant with the schema and output, and the description could be more front-loaded with key details.

  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 the tool's moderate complexity (1 parameter with nested object), rich annotations, and an output schema, the description is minimally adequate. It covers the basic action and parameters but lacks context on errors, dependencies (e.g., BTT setup), or integration with sibling tools. The output schema handles return values, so the description doesn't need to detail them.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the description lists parameters: 'Notification title, subtitle, sound, and optional image.' This adds some semantics beyond the schema's property names. However, it omits the 'connection' parameter entirely and doesn't explain parameter interactions or constraints (e.g., 'title' is required). The description partially compensates but not fully.

  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's purpose: 'Display a macOS notification via BTT.' It specifies the verb ('Display'), resource ('macOS notification'), and technology ('BTT'). However, it doesn't explicitly differentiate from sibling tools like btt_trigger_action or btt_trigger_named, which might also involve notifications indirectly.

  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. It doesn't mention sibling tools, prerequisites (e.g., BTT must be running), or scenarios where this is appropriate (e.g., for user alerts vs. system events). Usage is implied but not explicitly stated.

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

• btt_get_clipboardB
  3.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, covering the safety profile. The description adds useful context about format options (plain text, HTML, images as base64) and the ability to return base64 encoding, which goes beyond annotations. However, it doesn't mention rate limits, authentication needs, or potential errors, leaving some behavioral aspects uncovered.

  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 well-structured with clear sections (purpose, capabilities, args, returns) and uses bullet-like formatting for format examples. It's appropriately sized without unnecessary elaboration, though the 'Args' and 'Returns' sections could be slightly more detailed without sacrificing conciseness.

  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 moderate complexity, rich annotations (readOnlyHint, idempotentHint), and the presence of an output schema, the description is reasonably complete. It covers the core functionality, parameter intent, and return value at a high level. However, it could benefit from more detailed usage examples or error handling information to achieve a perfect score.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the description provides a high-level overview of parameters ('Format to retrieve and whether to return as base64') and return values ('Clipboard content'). This adds meaningful context beyond the bare schema, though it lacks detailed syntax or format examples. Given the schema's lack of descriptions, the description compensates moderately, warranting a baseline 3.

  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's purpose with a specific verb ('Get') and resource ('current clipboard content'), and distinguishes it from its sibling 'btt_set_clipboard'. However, it doesn't explicitly differentiate from other clipboard-related tools that might exist in other contexts, keeping it at a 4 rather than 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. While it mentions retrieving content in various formats, it doesn't specify scenarios where this tool is preferred over other clipboard access methods or when to choose specific formats. This lack of contextual usage advice results in a score of 2.

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

• btt_get_preset_detailsB
  3.2/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the agent knows this is a safe, repeatable read operation. The description adds some behavioral context by mentioning the return format options (markdown or JSON), which isn't covered by annotations. However, it doesn't disclose rate limits, authentication needs, or error conditions beyond what annotations provide.

  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 well-structured and appropriately sized with four sentences: purpose statement, return information summary, args explanation, and returns clarification. Each sentence adds value, though the 'Args' and 'Returns' sections could be integrated more naturally. No wasted words, but minor structural improvements are possible.

  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 has annotations (readOnlyHint, idempotentHint), an output schema exists, and it's a simple read operation with one main parameter, the description is reasonably complete. It covers the core purpose, parameter intent, and return format options. The main gap is lack of sibling differentiation, but otherwise provides sufficient context for agent selection and invocation.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the description compensates by explaining the 'params' parameter contains the preset name to query and mentions the response format options. However, it doesn't detail the connection configuration or other nested parameters. With 0% schema coverage, the description adds some value but doesn't fully document all parameter semantics, especially for the complex BTTConnectionConfig object.

  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's purpose: 'Get details about a specific preset' with specific verb ('Get') and resource ('preset'). It distinguishes from siblings by focusing on preset details rather than triggers, variables, or clipboard operations, though it doesn't explicitly contrast with btt_export_preset or btt_import_preset which also handle presets.

  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. It doesn't mention when to use btt_get_preset_details versus btt_get_trigger, btt_get_triggers, or btt_list_named_triggers for related information, nor does it specify prerequisites like needing the preset name. The only implied usage is when you need preset details, but no exclusions or alternatives are provided.

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

• btt_set_clipboardB
  3.2/5.0
  Behavior3/5

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

  Annotations provide readOnlyHint=false (correct for a write operation), idempotentHint=true, and destructiveHint=false. The description adds minimal behavioral context beyond annotations - it mentions 'various formats including plain text and HTML' which provides useful implementation detail, but doesn't describe error conditions, permissions needed, or system-specific behaviors. No contradiction with annotations exists.

  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 well-structured and appropriately sized at 4 sentences. It front-loads the core purpose, then adds format details, followed by parameter and return value sections. Each sentence serves a purpose, though the parameter section could be more informative given the schema coverage gap.

  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 the tool has annotations (covering safety profile), an output schema (handling return values), and 1 parameter with 0% schema coverage, the description is moderately complete. It covers the basic operation and format options but lacks usage guidance, detailed parameter explanations, and system-specific considerations that would be helpful for a clipboard manipulation tool.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description carries full burden for parameter documentation. The description mentions 'Content to set and format' which maps to the 'params' object containing 'content' and 'format' fields, but provides no details about the connection configuration parameter or format options. It adds some meaning but doesn't fully compensate for the schema coverage gap.

  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's purpose: 'Set the clipboard content' with the verb 'set' and resource 'clipboard content'. It distinguishes from sibling btt_get_clipboard by being the write operation, though it doesn't explicitly mention this distinction. The description is specific about what the tool does but could be more explicit about sibling differentiation.

  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. It doesn't mention when this tool is appropriate versus other clipboard-related tools (like btt_get_clipboard) or when not to use it. There's no context about prerequisites or constraints beyond what's implied by the action itself.

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

• btt_update_triggerB
  3.2/5.0
  Behavior3/5

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

  Annotations already indicate this is a mutation tool (readOnlyHint: false) that's idempotent and non-destructive. The description adds minimal behavioral context beyond this - it mentions providing a UUID and JSON object, but doesn't disclose important traits like authentication requirements (implied by connection config), potential side effects, error conditions, or rate limits. No contradiction with annotations exists.

  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 efficiently structured with a clear purpose statement followed by parameter and return value sections. Each sentence serves a distinct purpose without redundancy. However, the 'Args' and 'Returns' sections could be more integrated with the main description rather than appearing as separate bullet points.

  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 this is a mutation tool with idempotent but non-destructive behavior, the description provides basic context but lacks important details. While an output schema exists (reducing need to describe returns), the description doesn't address authentication requirements, error handling, JSON format specifics, or how this tool relates to the broader trigger management workflow with sibling tools.

  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?

  With 0% schema description coverage, the description carries full burden for parameter documentation. It identifies that 'params' contains UUID and JSON properties to update, which matches the schema structure. However, it doesn't explain the JSON format requirements, connection configuration details, or provide examples of valid update properties, leaving significant gaps in parameter understanding.

  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 action ('Update an existing trigger's configuration') and identifies the resource ('trigger'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this from sibling tools like 'btt_update_widget' or explain how updating a trigger differs from related operations like 'btt_add_trigger' or 'btt_get_trigger'.

  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. It doesn't mention prerequisites (e.g., needing an existing trigger UUID), compare with sibling tools like 'btt_add_trigger' for creation or 'btt_delete_trigger' for removal, or indicate scenarios where partial updates are appropriate versus other methods.

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

• btt_export_presetA
  3.5/5.0
  Behavior3/5

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

  Annotations already indicate this is a read-only, non-destructive, idempotent operation (readOnlyHint: true, destructiveHint: false, idempotentHint: true). The description adds minimal behavioral context beyond this, mentioning the file export purpose but not detailing aspects like authentication needs (implied by connection config) or rate limits. With annotations covering key safety traits, the description provides some value but not rich behavioral disclosure.

  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 well-structured with clear sections (purpose, usage, Args, Returns) and uses only four sentences. It's front-loaded with the core purpose and avoids unnecessary verbosity, though the Args section could be more detailed given the parameter complexity.

  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 moderate complexity (1 parameter with nested properties), rich annotations (readOnlyHint, idempotentHint, etc.), and the presence of an output schema (implied by 'Returns' in description), the description is reasonably complete. It covers purpose, usage, parameters at a high level, and return value, though it could benefit from more detailed parameter explanations to compensate for the 0% schema description coverage.

  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 0%, but the description briefly mentions 'Preset name and export options' in the Args section, which partially maps to the nested 'params' object properties (name, output_path, compress, include_settings, connection). However, it doesn't fully compensate for the lack of schema descriptions, leaving many parameter details unclear. The baseline is 3 since the description adds some semantic context but doesn't fully explain the parameters.

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

  Purpose4/5

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

  The description clearly states the action ('Export a BTT preset to a file') and resource ('BTT preset'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'btt_import_preset' beyond the export/import distinction, which is why it doesn't reach a perfect score.

  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 provides implied usage context ('Useful for backing up configurations or sharing presets'), which gives some guidance on when to use this tool. However, it doesn't explicitly state when not to use it or mention alternatives like 'btt_get_preset_details' for viewing without exporting, leaving room for improvement.

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

• btt_get_triggersA
  3.5/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, read-only operation. The description adds value by mentioning the tool's purpose for 'explore and understand the current BTT configuration,' which provides context beyond annotations. However, it doesn't disclose additional behavioral traits like rate limits, authentication needs, or pagination behavior. With annotations covering safety, a 3 is appropriate for adding some context.

  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 appropriately sized and front-loaded: the first sentence states the purpose, followed by usage guidance and parameter/return details. Every sentence adds value, with no redundant information. However, the structure could be slightly improved by more clearly separating sections (e.g., bullet points for filters), but it remains efficient and well-organized.

  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 complexity (1 parameter with nested filtering options), rich annotations (read-only, idempotent), and the presence of an output schema (implied by 'Returns' section), the description is mostly complete. It explains the tool's purpose, usage context, filtering capabilities, and output format. However, it lacks details on error handling or specific examples of trigger types, which could enhance completeness for a retrieval tool with filtering.

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

  Parameters3/5

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

  Schema description coverage is 0%, meaning the schema provides no descriptions for parameters. The description compensates by listing filter options: 'trigger type, parent folder, specific app, or get all triggers,' and mentions 'response_format setting' for output. However, it doesn't fully explain the 'params' object structure or all available filters beyond the examples given. Since schema coverage is low, the description adds meaningful but incomplete parameter semantics, warranting a baseline 3.

  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's purpose: 'Retrieve triggers from BetterTouchTool with optional filtering.' It specifies the verb ('retrieve') and resource ('triggers'), and mentions filtering capabilities. However, it doesn't explicitly differentiate from sibling tools like 'btt_get_trigger' (singular) or 'btt_list_named_triggers', which reduces the score from a perfect 5.

  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 provides some usage context: 'Use this tool to explore and understand the current BTT configuration.' This implies it's for exploration rather than modification, but it doesn't explicitly state when to use this tool versus alternatives like 'btt_get_trigger' (singular) or 'btt_list_named_triggers'. No explicit exclusions or prerequisites are mentioned, leaving usage guidance at an implied level.

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

• btt_set_variableA
  3.5/5.0
  Behavior4/5

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

  The description adds valuable behavioral context beyond annotations: it explains persistence behavior (surviving BTT restart vs runtime-only) and mentions the return value confirmation. Annotations already indicate idempotentHint=true and destructiveHint=false, but the description provides specific implementation details about persistence that aren't captured in structured fields.

  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 well-structured with clear sections: purpose statement, behavioral context, Args, and Returns. Each sentence earns its place, though the Args section could be more informative. The information is front-loaded with the core purpose stated first.

  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 that there's an output schema (which handles return values) and annotations provide safety/behavior hints, the description covers the essential aspects: what the tool does, persistence behavior, and basic parameter overview. For a tool with good structured data support, this description provides adequate contextual information without being overly verbose.

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

  Parameters2/5

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

  With 0% schema description coverage, the description carries full burden for parameter documentation. While it mentions 'Variable name, value, type, and persistence setting' in the Args section, this is just a list without explaining what each parameter means, their formats, or how they interact. The schema provides detailed descriptions, but the tool description itself adds minimal semantic value beyond naming the parameters.

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

  Purpose4/5

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

  The description clearly states the action ('Set a BTT variable') and the target ('to a specified value'), providing a specific verb+resource combination. It distinguishes from siblings like 'btt_get_variable' by focusing on setting rather than retrieving. However, it doesn't explicitly contrast with other variable-related tools if they exist.

  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 mentions that variables can be persistent or runtime-only, which provides some context for when to use persistence settings. However, it doesn't explicitly state when to use this tool versus alternatives like 'btt_update_trigger' or 'btt_set_clipboard', nor does it provide clear exclusions or prerequisites for usage.

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

• btt_update_widgetA
  3.5/5.0
  Behavior3/5

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

  The description adds some behavioral context beyond annotations: it clarifies that updates are 'temporary' and don't change underlying configuration. However, annotations already provide idempotentHint=true and destructiveHint=false, so the safety profile is covered. The description doesn't address rate limits, authentication needs, or what happens on failure. No contradiction with annotations exists.

  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 appropriately sized with three sentences: purpose statement, behavioral clarification, and parameter/return summaries. It's front-loaded with the core purpose. The 'Args:' and 'Returns:' sections are slightly redundant with the schema but help readability. No wasted sentences, though could be more tightly integrated.

  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 has annotations (idempotent, non-destructive), an output schema (returns confirmation), and moderate complexity, the description provides adequate context. It covers purpose, temporary nature, and parameter overview. However, it lacks details on authentication (shared_secret in schema), error handling, and exact return format, leaving some gaps for a mutation tool.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description carries full burden. It mentions 'Widget UUID, type, and display properties to update,' which maps to the single 'params' parameter and its nested structure. However, it doesn't explain specific fields like 'text', 'icon_path', or 'background_color' format, leaving significant gaps. The baseline is 3 since it provides some parameter context but doesn't fully compensate for the 0% schema coverage.

  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 action ('update the display') and resource ('Touch Bar, Menubar, or Stream Deck widget'), making the purpose immediately understandable. It distinguishes this from configuration changes by noting it's 'temporary updates to widget appearance without changing the underlying configuration,' though it doesn't explicitly differentiate from sibling tools like btt_refresh_widget or btt_update_trigger.

  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 context by stating this is for 'temporary updates to widget appearance' rather than configuration changes, but provides no explicit guidance on when to use this versus alternatives like btt_refresh_widget or btt_update_trigger. There's no mention of prerequisites, error conditions, or when-not-to-use scenarios.

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

• btt_trigger_namedA
  3.6/5.0
  Behavior3/5

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

  Annotations provide key hints (readOnlyHint=false, openWorldHint=true, etc.), and the description adds useful context: it describes the return behavior ('Result of the trigger execution (if wait_for_reply is True)') and notes triggers can perform 'any sequence of actions.' However, it doesn't detail potential side effects, error handling, or performance implications beyond what annotations cover.

  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 well-structured with a clear purpose statement, context, and separate Args/Returns sections. It's appropriately sized with no redundant information, though the 'Args' and 'Returns' labels could be more integrated into the flow.

  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 moderate complexity (1 parameter with nested schema), annotations covering key behaviors, and an output schema, the description is fairly complete. It explains what the tool does, parameter intent, and return conditions, though it could better address sibling tool differentiation and edge cases.

  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 description coverage is 0%, so the description must compensate. It explains 'params' contains 'trigger_name and whether to wait for completion,' clarifying the purpose of the nested parameters. This adds meaningful semantics beyond the bare schema, though it doesn't detail the 'connection' sub-parameter or default values.

  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's purpose: 'Execute a named trigger by its name' with additional context about where triggers are configured. It distinguishes from siblings like 'btt_execute_trigger' by specifying 'named' triggers, though it doesn't explicitly contrast with 'btt_trigger_action' which might be similar.

  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 context by mentioning triggers are 'configured in BTT's 'Other' tab' and can perform 'any sequence of actions,' but lacks explicit guidance on when to use this versus alternatives like 'btt_execute_trigger' or 'btt_trigger_action.' No exclusions or prerequisites are stated.

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

• btt_add_triggerA
  3.7/5.0
  Behavior3/5

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

  Annotations already declare readOnlyHint=false, destructiveHint=false, etc., so the agent knows this is a non-destructive write operation. The description adds useful context about JSON format requirements and copying from existing triggers, but doesn't mention authentication needs (shared_secret), rate limits, or what happens on duplicate triggers. With annotations covering basic safety, this adds moderate behavioral context.

  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 well-structured with clear sections (purpose, args, returns) and uses bullet-like formatting. It's appropriately sized at 5 sentences, though the JSON format explanation could be slightly more concise. Most sentences earn their place by providing necessary 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?

  Given the tool's moderate complexity (write operation with JSON input), annotations provide basic safety info, and an output schema exists (so return values are documented elsewhere), the description covers the essential purpose and parameter concepts. The main gap is incomplete parameter coverage (missing connection config explanation), but otherwise provides reasonable context for agent understanding.

  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?

  With 0% schema description coverage, the description carries full burden for parameter documentation. It mentions 'trigger JSON definition' and 'optional parent UUID' which map to trigger_json and parent_uuid parameters, but doesn't address the connection parameter at all. The description adds some semantic value but doesn't fully compensate for the complete lack of schema descriptions.

  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 specific action ('Add a new trigger') and resource ('to BetterTouchTool'), distinguishing it from siblings like btt_update_trigger (modify existing) or btt_delete_trigger (remove). It provides a complete verb+resource+scope statement that leaves no ambiguity about what this tool does.

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

  Usage Guidelines3/5

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

  The description implies usage through the instruction to copy JSON format from existing triggers, but doesn't explicitly state when to use this vs alternatives like btt_update_trigger or btt_trigger_named. No explicit when-not-to-use guidance or prerequisite information is provided, leaving usage context somewhat implied rather than clearly defined.

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

• btt_get_variableA
  3.8/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, indicating a safe, non-mutating operation. The description adds valuable context by explaining the types of variables (built-in and user-defined) and specifying the return value ('Current value of the variable'), which enhances understanding beyond the annotations. No contradictions with annotations are present.

  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 well-structured and front-loaded, with the core purpose in the first sentence, followed by context and a clear Args/Returns breakdown. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.

  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 low complexity (1 parameter), rich annotations (readOnlyHint, idempotentHint), and the presence of an output schema (which handles return values), the description is largely complete. It covers the tool's purpose, variable types, and parameter basics. However, it could improve by addressing potential errors (e.g., if a variable doesn't exist) or connection requirements, slightly reducing 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?

  The schema description coverage is 0%, meaning parameters are undocumented in the schema. The description compensates by listing 'Variable name and type (string or number)' in the Args section, which clarifies the purpose of the single parameter 'params'. However, it doesn't detail the nested structure (e.g., connection configuration) or provide examples, leaving some gaps in parameter understanding.

  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's purpose: 'Get the value of a BTT variable.' It specifies the verb ('Get') and resource ('BTT variable'), and distinguishes it from siblings like btt_set_variable. However, it doesn't explicitly differentiate from other read operations like btt_get_trigger or btt_get_triggers, which prevents a perfect score.

  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 provides implied usage context by mentioning 'BTT has many built-in variables (like BTTActiveAppBundleIdentifier) and supports user-defined variables,' which suggests when this tool is applicable. However, it lacks explicit guidance on when to use this tool versus alternatives like btt_get_trigger for different data types, or prerequisites for accessing variables.

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

• btt_reveal_in_uiA
  3.8/5.0
  Behavior4/5

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

  Annotations provide readOnlyHint=false, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context beyond annotations: it specifies that the tool 'opens BTT and navigates to the specified element,' indicating UI interaction and potential side effects (application focus change), which annotations don't cover. No contradiction with annotations.

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

  Conciseness4/5

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

  The description is well-structured with purpose, action, and parameter/return sections in four concise sentences. However, the 'Args' and 'Returns' labels are redundant with the schema and could be omitted for better front-loading of essential 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?

  Given the tool's moderate complexity (UI interaction, nested parameters) and the presence of annotations and output schema, the description is mostly complete. It covers purpose and behavior well, but the parameter gap (missing 'connection' details) prevents a perfect score, as the schema alone doesn't fully compensate due to 0% description coverage.

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

  Parameters2/5

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

  Schema description coverage is 0%, so the description must compensate. It only mentions 'UUID of the element to reveal' for the 'params' parameter, but the schema reveals 'params' is a nested object with 'uuid' and 'connection' sub-properties. The description fails to explain the 'connection' configuration or its defaults, leaving significant parameter semantics undocumented.

  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 specific action ('reveal a trigger or element in the BetterTouchTool UI') and resource ('trigger or element'), distinguishing it from siblings like btt_get_trigger (read-only) or btt_update_trigger (modify). The phrase 'for editing' further clarifies the intent beyond simple viewing.

  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 needing to locate and edit a specific element in the BTT UI, but provides no explicit guidance on when to choose this over alternatives like btt_get_trigger (for details without UI navigation) or btt_update_trigger (for direct modification). The context is clear but lacks comparative guidance.

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

• btt_get_triggerA
  4/5.0
  Behavior3/5

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

  Annotations already provide readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the agent knows this is a safe, non-destructive read operation. The description adds useful context about what information is returned ('detailed information... including all its configuration and assigned actions') and the return format options, which goes beyond the annotations.

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

  Conciseness5/5

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

  The description is perfectly structured and concise: a clear purpose statement, usage context, Args section, and Returns section - all in 4 sentences with zero wasted words. Every sentence earns its place by providing essential 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 read-only tool with good annotations and an output schema, the description is mostly complete. It explains what the tool does, what it returns, and the parameter purpose. However, given the 0% schema coverage and complex nested parameter structure, it could provide more guidance on the connection configuration parameters that aren't mentioned in the description.

  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?

  With 0% schema description coverage, the description carries the full burden of parameter documentation. It mentions that 'params contains the UUID of the trigger to retrieve' and implies format options in the Returns section, but doesn't fully explain the nested structure (connection config, response_format) or provide syntax details. The description adds some value but doesn't fully compensate for the schema coverage gap.

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

  Purpose5/5

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

  The description clearly states the specific action ('Retrieve a specific trigger by its UUID') and resource ('trigger'), distinguishing it from siblings like btt_get_triggers (plural) which likely lists multiple triggers. It explicitly mentions retrieving detailed information including configuration and assigned actions.

  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 for when to use this tool ('to get detailed information about a single trigger'), but doesn't explicitly state when not to use it or name alternatives. It implies usage for single-trigger retrieval versus btt_get_triggers for multiple triggers, but doesn't make this distinction explicit.

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

• btt_refresh_widgetA
  4/5.0
  Behavior4/5

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

  Annotations provide idempotentHint=true and destructiveHint=false, but the description adds valuable context about what the tool actually does (re-executes scripts to update display) and mentions the return value (confirmation). This goes beyond the annotations by explaining the functional behavior and output.

  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 perfectly structured: purpose statement first, usage context second, then parameter and return documentation. Every sentence adds value with zero waste. The formatting with clear sections (Args, Returns) enhances readability.

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

  Completeness3/5

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

  For a tool with idempotent behavior and an output schema (which handles return values), the description covers the core purpose well. However, the complete omission of the connection parameter documentation creates a significant gap, especially since this tool likely requires network/authentication configuration.

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

  Parameters2/5

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

  With 0% schema description coverage, the description carries full burden for parameter documentation. It only mentions 'UUID of the widget to refresh' but completely omits the 'connection' parameter (BTTConnectionConfig with host, port, shared_secret, use_cli). This leaves critical connection configuration undocumented.

  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 specific action ('refresh a script widget to re-execute its scripts') and the resource ('widget'). It distinguishes from siblings like btt_update_widget (which likely modifies settings) by focusing on re-execution rather than configuration changes.

  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 for when to use this tool ('force a widget to update its display by running its assigned scripts again'), but doesn't explicitly mention when not to use it or name specific alternatives among siblings. The guidance is helpful but lacks explicit exclusions.

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

• btt_trigger_actionA
  4/5.0
  Behavior3/5

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

  Annotations provide readOnlyHint=false, openWorldHint=true, idempotentHint=false, and destructiveHint=false. The description adds useful context about the JSON source mechanism and mentions the return value, but doesn't elaborate on behavioral aspects like authentication requirements (implied by connection config), potential side effects of triggering actions, or rate limits. It doesn't contradict annotations.

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

  Conciseness5/5

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

  The description is perfectly structured with three focused sentences: purpose statement, JSON acquisition method, and parameter/return explanation. Every sentence earns its place with zero wasted words, and key 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?

  Given the tool's complexity (triggering arbitrary actions via JSON), the description is reasonably complete. It explains the core mechanism and JSON source. With annotations covering safety profile and an output schema presumably describing returns, the main gap is lack of guidance about when to choose this over sibling tools like btt_trigger_named.

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

  Parameters3/5

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

  Schema description coverage is 0%, but the description compensates by explaining that 'params' contains 'the action JSON definition' and how to obtain it. However, it doesn't detail the structure of the nested connection configuration or wait_for_reply parameter. The baseline is 3 since the description adds some meaning beyond the bare 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 specific verb ('trigger') and resource ('any BTT predefined action') with the mechanism ('using a JSON definition'). It distinguishes from siblings like btt_trigger_named (which likely uses names rather than JSON) and btt_execute_trigger (which might have different semantics).

  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 about when to use this tool ('Trigger any BTT predefined action using a JSON definition') and how to obtain the required JSON ('by right-clicking a configured trigger in BTT'). However, it doesn't explicitly state when NOT to use it or name specific alternatives among the many sibling tools.

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

• btt_delete_triggerA
  4.2/5.0
  Behavior4/5

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

  Annotations already indicate destructiveHint=true, but the description adds valuable context beyond this by explicitly stating 'This permanently removes the trigger' and emphasizing the need for correct UUID. It doesn't contradict annotations (which correctly mark it as non-readOnly and destructive) and provides additional behavioral insight about the irreversible nature of the 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 perfectly structured and concise: a clear purpose statement, a critical warning, and brief parameter/return sections. Every sentence earns its place, with no redundant information. The warning is appropriately front-loaded for a destructive operation, making it highly 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?

  For a destructive tool with good annotations and an output schema (which handles return values), the description is mostly complete. It covers the irreversible nature and UUID requirement well. The main gap is the incomplete parameter documentation (missing connection config details), but given the output schema exists and annotations provide safety context, it's reasonably 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?

  With 0% schema description coverage, the description carries the full burden of parameter documentation. It mentions that 'params' contains the UUID of the trigger to delete, which provides basic semantics for the uuid parameter. However, it doesn't address the nested connection configuration object within params, leaving significant gaps in parameter understanding despite the schema's structural details.

  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 specific action ('Delete a trigger from BetterTouchTool') and resource ('trigger'), distinguishing it from siblings like btt_update_trigger (update) and btt_get_trigger (read). It provides a precise verb+resource combination that leaves no ambiguity about the tool's function.

  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 for when to use this tool (to permanently remove a trigger) and includes a WARNING about ensuring correct UUID, which implies caution. However, it doesn't explicitly mention when NOT to use it or name specific alternatives like btt_update_trigger for modifications instead of deletion, which prevents a perfect score.

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

• btt_list_named_triggersA
  4.3/5.0
  Behavior4/5

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

  While annotations already indicate this is a read-only, non-destructive, idempotent operation, the description adds valuable behavioral context: it specifies the return format ('List of named triggers with their names and UUIDs') and clarifies the scope ('all named triggers'). This goes beyond what annotations provide about safety and adds useful operational details.

  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 perfectly structured with three focused sentences: purpose statement, context about named triggers, and return specification. Every sentence adds essential information with zero redundancy or filler content. It's front-loaded with the core functionality.

  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 the tool has comprehensive annotations (readOnlyHint, idempotentHint, etc.), a detailed input schema with 100% parameter documentation, and an output schema (implied by 'Returns:' statement), the description provides exactly what's needed: clear purpose, context about what named triggers are, and return format. No additional information is required for this read-only listing operation.

  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?

  With 0% schema description coverage, the description carries the full burden but provides no parameter information. The schema comprehensively documents the single 'params' object with its nested properties (connection configuration and response_format), so the baseline of 3 is appropriate since the schema does all the parameter documentation work.

  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 specific action ('List all named triggers') and resource ('configured in BetterTouchTool'), with additional context about what named triggers are. It distinguishes from siblings like btt_get_trigger (singular) and btt_get_triggers (general triggers) by focusing specifically on named triggers from the 'Other' tab.

  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 about when to use this tool ('triggers configured in the 'Other' tab that can be called by name from scripts or other actions'), which implicitly distinguishes it from general trigger tools. However, it doesn't explicitly state when NOT to use it or name specific alternative tools for different scenarios.

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