Server Quality Checklist

Tool Scores

• hookmark_frontmostA
  4/5.0
  Behavior3/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 describes key behaviors: bringing the app to the foreground, creating a bookmark, and returning a URL. However, it lacks details on error handling, permissions needed, or what happens if the app is not running or has no active document.

  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 front-loaded with the core purpose, followed by specific instructions and examples. Every sentence adds value: the first states the action, the second explains the return value usage, and the third clarifies parameter formatting. No wasted words.

  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 (2 parameters, no annotations, no output schema), the description is fairly complete. It covers the purpose, usage, and parameter semantics adequately. However, it could improve by addressing potential errors or edge cases, such as what happens if the app is not installed or has no frontmost document.

  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 documents both parameters thoroughly. The description adds minimal value beyond the schema, mentioning the app name format and the markdown option's purpose, but does not provide additional syntax or usage details for 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 clearly states the tool's purpose with specific verbs ('Get', 'Brings', 'creates') and resources ('hook:// URL', 'active document or window', 'Hookmark bookmark'). It distinguishes from siblings by focusing on creating a bookmark for the frontmost application rather than cloning, connecting, listing, removing, or searching existing bookmarks.

  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 on when to use this tool: to get a hook:// URL for the active item in a specified macOS app, which can then be used with hookmark_connect. It mentions the app name format requirement but does not explicitly state when not to use it or name specific alternatives among siblings.

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

• hookmark_searchA
  4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: the search scope (names and URLs by default), output format options, and restrictions (names_only, files_only). However, it lacks details on rate limits, error handling, or authentication needs, leaving some gaps in 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 front-loaded with the core purpose, followed by specific usage details in a logical flow. Each sentence adds essential information without redundancy, making it highly efficient and well-structured for quick understanding.

  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 (4 parameters, no output schema, no annotations), the description is mostly complete. It covers the search behavior, output formats, and key parameters, but could improve by mentioning potential limitations or example use cases. Without annotations or output schema, it adequately informs but has minor gaps.

  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 documents all parameters thoroughly. The description adds minimal value beyond the schema, mentioning 'format' options and 'names_only' briefly, but does not provide additional semantic context or examples. This meets the baseline for high schema coverage.

  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 ('Search Hookmark bookmarks by keyword'), resource ('Hookmark bookmarks'), and scope ('both bookmark names and URLs by default'), distinguishing it from siblings like hookmark_list or hookmark_remove. It explicitly defines the tool's function without being vague or tautological.

  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 its explanation of search behavior (e.g., 'by default' searches names and URLs, with options to restrict), but does not explicitly state when to use this tool versus alternatives like hookmark_list or hookmark_search. It provides some context but lacks direct guidance on tool selection among siblings.

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

• hookmark_cloneA
  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 of behavioral disclosure. It does well by explicitly stating this is a copy operation that doesn't modify the source item's hooks, which clarifies important behavioral traits. However, it doesn't mention potential side effects, error conditions, or what happens if hooks already exist on the destination, leaving some gaps.

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

  Conciseness5/5

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

  The description is efficiently structured with three sentences that each add value: the core operation, clarification about source preservation, and usage context. There's no wasted text, and the most important information (what the tool does) comes 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?

  For a tool with 2 parameters, 100% schema coverage, and no output schema, the description provides good context about the operation's purpose and behavior. However, as a mutation tool with no annotations, it could benefit from more detail about potential side effects or error conditions to be 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?

  With 100% schema description coverage, the schema already documents both parameters thoroughly. The description doesn't add meaningful parameter semantics beyond what's in the schema - it mentions 'source' and 'destination' but doesn't provide additional context about format constraints or usage patterns. This meets the baseline for high schema coverage.

  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 ('Clone all hooks'), identifies the resources involved ('from one item onto another'), and distinguishes this from sibling tools by specifying it's a copy operation that doesn't modify the source. It goes beyond just restating the name by explaining what cloning hooks means in practice.

  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 ('Useful when duplicating a file or moving content to a new location'), which helps the agent understand appropriate scenarios. However, it doesn't explicitly contrast with specific sibling tools or provide 'when-not-to-use' guidance, keeping it at a 4 rather than a 5.

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

• hookmark_connectA
  4.2/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 the bidirectional nature and outcome of the operation, but lacks details on permissions, error conditions, rate limits, or whether the operation is idempotent. It adequately describes the core behavior but misses advanced operational 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?

  Three sentences with zero waste: first states purpose and input requirements, second explains outcome, third provides prerequisite guidance. Each sentence adds essential information, and the description is appropriately front-loaded with the core action.

  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 (bidirectional linking), no annotations, and no output schema, the description is mostly complete. It covers purpose, usage, and prerequisites well, but lacks details on return values, error handling, or edge cases, which would be helpful for full contextual 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?

  Schema description coverage is 100%, so the schema fully documents both parameters. The description adds marginal value by clarifying that items must be referenced by 'file path, URL, or hook:// URL' and mentioning sibling tools for obtaining hook:// URLs, but doesn't provide additional syntax or format details beyond what the schema already states.

  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 ('Create a bidirectional hook'), the resource ('between two items'), and distinguishes from siblings by mentioning alternative tools (hookmark_link, hookmark_frontmost) for obtaining required inputs. It goes beyond a tautology by explaining the bidirectional relationship and outcome.

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

  Usage Guidelines5/5

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

  Explicitly states when to use this tool ('After this call, each item will appear in the other's hook list') and provides clear alternatives for prerequisite steps ('Use hookmark_link or hookmark_frontmost to obtain hook:// URLs first'). It distinguishes from siblings by specifying the unique linking function.

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

• hookmark_removeA
  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 of behavioral disclosure. It effectively describes the mutation behavior ('removes the link from both directions') and the outcome ('after this call neither item will appear in the other's hook list'), which is crucial for a destructive operation. It doesn't mention error conditions or permissions, but provides solid 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.

  Conciseness5/5

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

  The description is efficiently structured in two sentences that each earn their place: the first states the purpose and requirements, the second explains the bidirectional effect. There's no wasted text, and key information is front-loaded appropriately.

  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 mutation tool with no annotations and no output schema, the description does well by explaining the action, requirements, and bidirectional effect. However, it lacks information about return values, error conditions, or confirmation messages, which would be helpful given the destructive nature. It's mostly complete but has minor gaps.

  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 has 100% description coverage, clearly documenting both parameters as file paths, URLs, or hook:// URLs. The description adds minimal value beyond the schema by reinforcing that 'both items must be referenced by their file path, URL, or hook:// URL,' which is already covered in the schema descriptions. This meets the baseline for high schema coverage.

  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 ('Remove a bidirectional hook between two items') and the resource involved ('bidirectional hook'), distinguishing it from sibling tools like hookmark_connect (create) or hookmark_list (read). It provides precise information about what the tool does beyond just the name.

  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 ('Remove a bidirectional hook between two items') and specifies that both items must be referenced by file path, URL, or hook:// URL. However, it doesn't explicitly mention when NOT to use it or name alternatives among siblings like hookmark_unlink or hookmark_disconnect if they existed.

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

• hookmark_linkA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden and does well by disclosing key behaviors: it generates a URL, copies it to the clipboard, returns the assigned URL, and accepts specific input types. It doesn't mention error conditions, rate limits, or permissions, but covers the core operation adequately.

  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?

  Three sentences with zero waste: first states the core action, second explains the return value and connection to another tool, third clarifies input acceptance. Each sentence earns its place with 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 single-parameter tool with no annotations and no output schema, the description is quite complete: explains what the tool does, when to use it, what it returns, and what inputs it accepts. The main gap is lack of error handling or edge case information, but it's sufficient for basic use.

  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 documents the single parameter. The description adds value by providing concrete examples ('/Users/you/note.md', 'https://example.com') and clarifying it accepts 'any URL', but doesn't add significant semantic meaning beyond what the schema provides.

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

  Purpose5/5

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

  The description clearly states the tool's purpose with specific verbs ('Generate', 'copy') and resources ('hook:// URL for a file or web URL'). It distinguishes from siblings by focusing on URL generation rather than connection, listing, searching, or removal operations.

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

  Usage Guidelines5/5

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

  Explicit guidance is provided on when to use this tool: 'Use this URL as a stable reference to the item when calling hookmark_connect.' This clearly distinguishes it from the sibling tool hookmark_connect and provides a specific use case.

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

• hookmark_listA
  4.4/5.0
  Behavior4/5

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

  With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool returns one item per line in specified formats, accepts various input types (file path, URL, hook:// URL), and can list all bookmarks if no item is provided. However, it lacks details on error handling, rate limits, or authentication needs, which are not covered.

  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 front-loaded with the core purpose, followed by format details and usage notes. Every sentence adds value without redundancy, making it efficient and well-structured for quick understanding.

  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 no annotations and no output schema, the description is fairly complete for a read-only list tool. It covers input types, format options, and a special case (no item). However, it could improve by mentioning potential outputs or error scenarios, but the lack of output schema is compensated by format explanations.

  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 documents all parameters thoroughly. The description adds minimal value beyond the schema, such as clarifying that omitting 'item' lists all bookmarks and briefly explaining format options, but does not provide significant additional semantics.

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

  Purpose5/5

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

  The description clearly states the verb ('List') and resource ('items hooked to a given file or URL'), specifying it returns one item per line. It distinguishes from siblings by focusing on listing hooks rather than cloning, connecting, linking, removing, or searching, which are different operations.

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

  Usage Guidelines5/5

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

  It explicitly states when to use this tool ('List all items hooked to a given file or URL') and provides alternatives for different formats. It also clarifies usage without an item to list all bookmarks, offering clear context for when to omit parameters.

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