Server Quality Checklist

Tool Scores

• get_collectionB
  3.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 adds useful context about credit usage ('No credits consumed') and API key handling via environment variables, but lacks details on error handling, rate limits, authentication requirements beyond the key, or response structure. This is adequate but has clear gaps for a read 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 well-structured with clear sections (Args, Returns, Credit Usage), front-loaded with the core purpose, and every sentence adds value without redundancy. It's appropriately sized for a simple retrieval tool.

  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 low complexity (2 parameters, no output schema, no annotations), the description is moderately complete. It covers purpose, parameters, and credit usage, but lacks output details (only mentions 'Dictionary with collection data or error message' vaguely) and doesn't integrate with sibling tools, leaving room for improvement.

  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 both parameters: 'collection_id' as 'The ID of the collection to retrieve' and 'api_key' with optionality and environment variable fallback. This adds meaningful semantics beyond the bare schema, though it doesn't cover format details like ID structure.

  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 verb ('Get') and resource ('a single collection by ID'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_collections' (plural) or 'get_collection_items', which would be needed for 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 Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like 'get_collections' or 'get_collection_items'. It mentions the optionality of 'api_key' but doesn't explain tool selection criteria, leaving the agent with minimal usage context.

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

• get_collection_itemsB
  3.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 adds useful context: credit usage (1 credit per swipe returned), pagination behavior (via cursor), and optional API key handling. However, it doesn't cover potential errors, rate limits, or authentication requirements beyond the API key note, leaving gaps for a mutation-free read 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 well-structured and front-loaded with the core purpose, followed by organized sections for args and returns. Every sentence adds value—no fluff or repetition—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.

  Completeness3/5

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

  Given no annotations, no output schema, and 0% schema coverage, the description does a decent job covering parameters and basic behavior (pagination, credit usage). However, it lacks details on error handling, response structure beyond 'dictionary', and sibling tool differentiation, making it incomplete for optimal agent use in this context.

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

  Parameters4/5

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

  Schema description coverage is 0%, so the description must compensate. It effectively explains all four parameters: collection_id (ID of the collection), api_key (optional with env var fallback), limit (range and default), and cursor (pagination). This adds significant meaning beyond the bare schema, though it could detail format constraints (e.g., collection_id structure).

  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 verb 'Get' and resource 'items (swipes) in a collection', making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like get_swipe or get_swipes, which might also retrieve swipe items, leaving some ambiguity about when to use this specific collection-focused retrieval.

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

  Usage Guidelines2/5

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

  The description provides no guidance on when to use this tool versus alternatives like get_swipe or get_swipes. It mentions the tool's function but lacks context about prerequisites (e.g., needing a collection ID) or comparisons to siblings, leaving the agent without clear usage direction.

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

• get_swipeB
  3.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 adds some context: it mentions credit usage ('Credit Usage: 1 credit'), which is useful for cost awareness, and hints at authentication behavior (API key optional if env var set). However, it lacks details on error handling, rate limits, or what 'swipe data' entails, leaving gaps for a read 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 well-structured and front-loaded: the first sentence states the purpose clearly, followed by organized sections for Args, Returns, and Credit Usage. Every sentence adds value without redundancy, making it efficient and easy to parse.

  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 no annotations and no output schema, the description is moderately complete. It covers the basic operation, parameters, and credit usage, but lacks details on return values (only 'Dictionary with swipe data or error message' is vague) and doesn't address potential errors or system limits. For a simple read tool, this is adequate but has clear gaps.

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

  Parameters4/5

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

  The schema description coverage is 0%, so the description must compensate. It adds meaningful semantics: 'swipe_id' is explained as 'The ID of the swipe to retrieve', and 'api_key' is described with optionality and environment variable fallback. This clarifies parameter purposes beyond the bare schema, though it doesn't cover format or constraints (e.g., ID structure).

  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 purpose: 'Get a single swipe by ID.' This specifies the verb ('Get') and resource ('swipe'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'get_swipes' (which likely retrieves multiple swipes), though the 'single' hint provides some distinction.

  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 like 'get_swipes' or 'get_collection_items', nor does it specify prerequisites or contexts for usage. The only usage hint is the optional 'api_key' parameter, which is insufficient for broader decision-making.

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

• get_swipesA
  3.9/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 adds valuable context: it explains authentication (API key or env var), pagination behavior (cursor parameter), credit usage (1 credit per swipe returned), and the return structure (dictionary with data, pagination, and credit info). This covers key operational aspects beyond basic input/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 well-structured and appropriately sized. It uses clear sections (Args, Returns, Credit Usage) with bullet-like formatting, making it easy to scan. Every sentence adds value—no redundant or vague statements. It's front-loaded with the core purpose, then details parameters and behavior efficiently.

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

  Completeness4/5

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

  For a tool with 5 parameters, no annotations, and no output schema, the description does an excellent job of covering essentials: purpose, parameters, return format, and credit usage. It's nearly complete, though it could slightly improve by explicitly mentioning error cases or rate limits. Given the context, it provides strong guidance for an agent.

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

  Parameters5/5

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

  Given 0% schema description coverage, the description fully compensates by providing detailed semantics for all 5 parameters. It explains each parameter's purpose, optionality, valid values (e.g., platform options, limit range), defaults, and environmental alternatives (API key). This adds significant meaning beyond the bare schema.

  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 swipes from your swipe file.' This specifies the verb ('Get') and resource ('swipes'), making it immediately understandable. However, it doesn't distinguish this tool from sibling tools like 'get_swipe' (singular) or 'get_collection_items', which might 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. It doesn't mention sibling tools like 'get_swipe' (singular) or 'get_collection_items', nor does it explain prerequisites like authentication requirements beyond the API key note. The agent must infer usage from the name and parameters alone.

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

• get_collectionsA
  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 full burden and does well by disclosing key behavioral traits: it specifies authentication options (API key or env var), pagination behavior, credit usage ('No credits consumed'), and return format. However, it doesn't mention rate limits, error conditions, or whether this is a read-only operation.

  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 (Args, Returns, Credit Usage) and efficiently communicates necessary information. However, the opening sentence could be more front-loaded with key differentiators, and some redundancy exists between the title-like opening and the detailed parameter explanations.

  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 4-parameter tool with no annotations and no output schema, the description provides good coverage: purpose, all parameters, return format, and credit usage. It could be more complete by explicitly stating this is a read operation and mentioning error cases, but overall it's substantially complete given the context.

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

  Parameters5/5

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

  Given 0% schema description coverage, the description compensates excellently by explaining all 4 parameters with clear semantics: api_key (optional with env var fallback), parent_id (filtering options with 'root' and 'None' semantics), limit (range and default), and cursor (pagination purpose). This adds substantial value beyond the bare schema.

  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 verb ('Get') and resource ('your collections (folders)'), making the purpose immediately understandable. However, it doesn't explicitly differentiate this from sibling tools like 'get_collection' (singular) or 'get_collection_items', leaving some ambiguity about scope.

  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 implied usage context through parameter explanations (e.g., filtering by parent_id, pagination), but doesn't explicitly state when to use this tool versus alternatives like 'get_collection' or 'get_collection_items'. No explicit when-not-to-use guidance or prerequisite information is provided.

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

• get_usageA
  4.2/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 states that no credits are consumed by using this tool, which is useful context, but does not cover other behavioral aspects like authentication needs beyond the API key note, rate limits, or error handling. It adds some value but is incomplete for a tool with no annotation coverage.

  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 appropriately sized and front-loaded, starting with the core purpose, followed by structured sections for arguments and returns. Every sentence adds value, with no redundant information, making it efficient and easy to parse.

  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 optional parameter, no output schema, no annotations), the description is mostly complete: it covers purpose, parameters, returns, and behavioral notes. However, it lacks details on error cases or advanced usage scenarios, leaving minor gaps in contextual understanding.

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

  Parameters4/5

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

  The input schema has 0% description coverage, but the description compensates by explaining the 'api_key' parameter's semantics: it's optional and can be set via an environment variable. This adds meaningful context beyond the schema, though it doesn't detail other potential parameters or constraints.

  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 a specific verb ('Get') and resource ('API credit usage for the current month'), distinguishing it from sibling tools that handle collections and swipes. It precisely defines what the tool retrieves without ambiguity.

  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 check API credit usage), but does not explicitly mention when not to use it or name alternatives. It implies usage for monitoring billing, though lacks explicit exclusions or comparisons to other tools.

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