Server Quality Checklist

Tool Scores

• shopify_upload_logo_from_urlA
  3.9/5.0
  Behavior3/5

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

  With no annotations, description covers the process (download, uploaded, staged upload) and requirements, but does not disclose potential failures, rate limits, or side effects. It gives a solid overview but misses some behavioral 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?

  Well-structured with sections (Process, Requirements, Example workflow). Every sentence adds value. Concise yet informative, 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 no output schema and 3 parameters, description provides process, requirements, example, and return value usage. It lacks error handling or response details, but overall covers essential context for using the tool.

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

  Parameters2/5

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

  Schema coverage is 0%, so description must compensate. It explains the 'url' parameter (public HTTPS) and mentions recommended dimensions, but does not clarify 'filename' or 'mimeType'. Partial coverage leaves ambiguity.

  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?

  Description clearly states action (upload), resource (logo image from URL to Shopify Files), and purpose (checkout branding). It distinguishes from sibling tool shopify_upload_custom_font_from_url by specifying 'logo' and 'checkout branding'.

  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?

  Provides explicit requirements (public HTTPS, supported formats, dimensions), context (for checkout branding), and an example workflow chaining with shopify_update_checkout_branding. Lacks explicit exclusions (e.g., when not to use), but overall strong guidance.

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

• shopify_update_checkout_brandingA
  4.1/5.0
  Behavior5/5

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

  With no annotations, the description fully addresses behavior: defaults to test profile, explains critical enum constraints (e.g., shadow, background mapping), notes API limitations (globalCornerRadius only NONE), and warns about live vs preview changes. No contradictions.

  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 lengthy but well-organized with headings and emojis, front-loading safety and key points. Every section earns its place given the tool's complexity, though some consolidation could improve conciseness.

  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 no annotations and no output schema, the description is remarkably complete: covers safety, all customization areas, simplified options, examples, and critical API notes. It leaves nothing essential unexplained.

  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?

  Schema coverage is 0%, but the description compensates thoroughly by explaining parameters like globalBrand, primaryButtonColor, and the full designSystem and customizations structures. Provides examples and maps enums to actual values, adding 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 'Update checkout branding using Shopify's CheckoutBrandingUpsert API', specifying the action and resource. However, it does not explicitly differentiate from sibling tools like shopify_get_checkout_branding, though the update focus is evident.

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

  Usage Guidelines2/5

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

  No explicit guidance on when to use this tool versus alternatives (e.g., get, list). The safety note about test vs production profiles is provided but does not cover when to choose this tool over others.

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

• shopify_get_checkout_brandingA
  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 the burden. It describes the read-only nature and the test default, but does not disclose potential errors, rate limits, or authentication requirements beyond implied safety.

  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 bullet points for the two main sections (design system and customizations), making it easy to read. It is slightly lengthy but justified by the complexity of the return object.

  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 no output schema, the description provides a comprehensive breakdown of the return structure, including specific fields under design system and customizations. This is complete enough for an agent to understand expected data.

  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 only parameter profileId has no schema description coverage (0%), but the description adds meaning by stating it is optional and defaults to TEST profile for safety. This provides functional context beyond the schema type 'string'.

  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 retrieves checkout branding configuration, specifying both the verb (retrieve) and resource (complete checkout branding configuration including design system and customizations). It distinguishes from sibling tools like update or upload.

  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 mentions that profileId is optional and defaults to TEST profile for safety, providing clear guidance on when to omit the parameter. However, it does not explicitly contrast with siblings like shopify_list_checkout_profiles or shopify_update_checkout_branding.

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

• shopify_upload_custom_font_from_urlA
  4.5/5.0
  Behavior4/5

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

  No annotations are provided, so the description bears full burden. It transparently describes the process (download, upload, return genericFileId), requirements (format, HTTPS), and usage patterns. However, it does not mention error handling, rate limits, or whether previous fonts are overwritten.

  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?

  Description is well-structured with sections and emojis, front-loading the purpose. It is comprehensive but slightly verbose (e.g., loading strategies section may be excessive). Every section adds value, but could be tightened.

  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?

  Despite lacking output schema, the description explains the return value (genericFileId) and provides complete examples for both primary and secondary fonts. It covers prerequisites, process, and integration with sibling tools, making it fully self-contained 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?

  Schema has 0% description coverage, but the description fully defines each parameter's meaning, defaults, and relationships (e.g., isBold sets fontWeight to 700). This compensates completely, adding significant semantic value beyond the schema.

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

  Purpose5/5

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

  Description explicitly states 'Upload a custom font from a public HTTPS URL to Shopify Files for use in checkout branding.' It clearly identifies the verb (upload), resource (custom font), and purpose (checkout branding), distinguishing it from sibling tools like shopify_upload_logo_from_url and checkout branding updates.

  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?

  Description provides detailed workflow steps, examples of integration with shopify_update_checkout_branding, and requirements (WOFF/HTTPS). It implies usage context but does not explicitly state when NOT to use or compare to alternatives like other font management tools.

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

• shopify_list_checkout_profilesA
  4.6/5.0
  Behavior4/5

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

  No annotations exist, so the description fully handles transparency. It explains that both TEST and PUBLISHED profiles are returned and notes typical store setup. However, it does not mention pagination or rate limits, though the simple nature of the tool (0 params) makes that less critical.

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

  Conciseness5/5

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

  The description is concise, uses a clear structure (main sentence, bullet points, note), and every sentence adds value without redundancy. It is front-loaded with the primary purpose.

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

  Completeness4/5

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

  Given the tool's simplicity (no params, no output schema), the description covers the key information: what the tool does, what it returns, and how to interpret results. It could include field names, but the mention of 'IDs, names, and publication status' is sufficient for most agents.

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

  Parameters4/5

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

  The tool has zero parameters, so schema coverage is trivially 100% and no parameter documentation is needed. Per guidelines, baseline for 0 params is 4.

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

  Purpose5/5

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

  The description uses a specific verb ('List') and resource ('checkout profiles in a Shopify Plus store'), and details what is returned (IDs, names, publication status). It clearly distinguishes itself from sibling tools that focus on branding 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?

  Explicitly provides three bullet-pointed use cases (identify before updates, find TEST profile, find PRODUCTION profile) and a note recommending to update TEST first, offering clear when-to-use and best-practice guidance.

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