Server Quality Checklist

Tool Scores

• get_account_by_emailA
  3.5/5.0
  Behavior2/5

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

  With no annotations, the description carries the full burden. It discloses that account details are returned 'if found', which hints at conditional behavior, but does not specify what happens when no account exists (e.g., empty response, error). It also omits any side effects or authentication requirements, though reads are likely safe.

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

  Conciseness5/5

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

  The description is a single, front-loaded sentence that directly states the action and expected result. Every word contributes meaning, with no redundant or filler content.

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

  Completeness4/5

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

  For a simple one-parameter lookup tool, the description covers the essential purpose and return outcome. It would benefit from specifying the not-found behavior and possibly a brief contrast with get_account, but these are minor gaps given the tool's low complexity.

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

  Parameters2/5

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

  Schema coverage is 0% and the description merely restates the parameter name ('email address'), adding no extra detail about format, validation, case-sensitivity, or expected input. Since the schema only declares a string type, the description fails to compensate for the low 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 uses a specific verb ('Look up') and resource ('FastSpring customer account') with a clear query method ('by email address'). It distinguishes itself from siblings like get_account, which likely uses an account ID, and get_account_orders, which focuses on orders.

  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 an email is known, but does not explicitly state when to prefer this tool over alternatives such as get_account (likely by ID) or list_orders_by_email. No exclusions or alternative references are provided, so guidance remains implicit.

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

• list_subscriptionsA
  3.8/5.0
  Behavior2/5

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

  The description states it searches within the current platform and returns a list, but it contradicts the input schema by saying 'Optionally filter by ... customer email' while email is a required parameter. It also lacks other behavioral disclosures like pagination or return format. The required-email mismatch is misleading and significant.

  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?

  Four concise sentences, each with a distinct purpose: state the action, mention filters, state the return, and provide an alternative. The description is front-loaded with the core purpose and contains no fluff.

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

  Completeness2/5

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

  With no output schema and no annotations, the description is the only source of behavioral information. It fails to mention that email is required, doesn't describe the list output structure or pagination, and omits any error or permission context. The alternative tool reference adds value but the gaps are significant for a list 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?

  Schema description coverage is only 33%, so the description should compensate. It adds meaning for 'status' (with examples active/deactivated) and clarifies 'product' as product name, but it doesn't explain the unusual email object type or resolve the optional-vs-required contradiction. This is partial compensation, not full.

  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 ('Search'), resource ('FastSpring subscriptions'), and scope ('current platform'). It also distinguishes itself from the sibling 'get_subscription' by explicitly noting it returns a list and pointing to get_subscription for full details.

  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?

  The description gives clear usage context: use this tool to search for subscriptions with optional filters, and explicitly names an alternative ('Use get_subscription to fetch the full details of a specific subscription'). This tells the agent when to prefer one tool over the other.

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

• get_accountA
  4/5.0
  Behavior3/5

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

  With no annotations, the description must carry the full burden. It states what the tool returns but does not explicitly disclose that it is read-only, mention error behavior, or side effects. 'Fetch' implies a safe read, providing adequate but not rich transparency.

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

  Conciseness5/5

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

  The description is two sentences, front-loaded with the action and resource, followed by return details. Every word earns its place, with no filler or repetition.

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

  Completeness4/5

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

  For a simple getter with one parameter and no output schema, the description covers the what, how, and return value. It misses explicit differentiation from get_account_by_email and potential error handling, but overall it is sufficiently complete.

  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 adds semantic meaning by identifying the parameter as the 'account ID', which is the key required. It does not elaborate on format or source, but for a single parameter this is sufficient.

  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 'Fetch' and the resource 'FastSpring customer account' with the specific lookup method 'by its account ID'. This distinguishes it from the sibling tool get_account_by_email, which fetches by email.

  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: users should call this when they have an account ID. However, it does not explicitly mention when not to use it or suggest alternatives like get_account_by_email, so the guidance is only implied, not explicit.

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

• get_account_ordersA
  4/5.0
  Behavior3/5

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

  With no annotations, the description must disclose behavior. It states the operation is a read ('Get all orders') and clarifies the required input, but it does not mention response format, pagination, errors, or permissions. This is minimally sufficient but not rich.

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

  Conciseness5/5

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

  The description is two concise sentences, front-loaded with the purpose, and contains no unnecessary words. Every phrase adds value.

  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 low complexity (single parameter, no output schema, no annotations), the description covers the essential purpose and parameter. It lacks explicit usage exclusions, but for a simple read tool it is sufficiently complete.

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

  Parameters3/5

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

  Schema description coverage is 0%, so the description must compensate. It explains that 'accountId' is the account whose order history is retrieved, but does not provide additional details about the ID format or source. This adds some meaning beyond the raw schema.

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

  Purpose5/5

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

  The description clearly states the tool retrieves all orders for a FastSpring customer account, with a specific verb ('Get') and resource ('orders'). It also distinguishes itself from siblings like get_order (single order) and list_orders_by_email (by email).

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

  Usage Guidelines4/5

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

  The description implies the use case: when you have a customer account ID and need full order history. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to select it over siblings.

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

• list_orders_by_emailA
  4/5.0
  Behavior3/5

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

  With no annotations, the description carries the full burden. It states the return type ('array of order objects') and platform context, which is useful. However, it does not disclose exact-match behavior for email, pagination, or potential side effects, leaving some uncertainty.

  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?

  Very concise: two sentences, each with a distinct purpose. The first states the tool's function, the second points to a sibling tool. No wasted words and the most important 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?

  For a simple one-parameter tool with no output schema, the description covers the essential purpose, return type, and a useful alternative. It lacks explicit pagination or exact-match details, but these are not critical given the low complexity.

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

  Parameters3/5

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

  The schema has 0% description coverage, so the description must compensate. It adds that the email identifies the customer, but it does not provide format details, matching rules, or additional parameter clarifications. Minimal compensation for the missing schema description.

  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' with a clear resource ('orders') and a defined scope ('by their email address'), making the tool's function immediately obvious. It also explicitly distinguishes itself from get_order by directing users there for full order details.

  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 offers a clear usage path: use this to list orders by email, then use get_order for full detail. However, it does not mention other sibling tools like get_account_orders or list_subscriptions, so the guidance is helpful but not exhaustive.

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

• create_quoteA
  4.1/5.0
  Behavior4/5

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

  With no annotations, the description carries the full burden. It discloses the return value (quoteUrl), the lifecycle (open until paid, cancelled, or expired; default 30 days), and that it appears in the dashboard. However, it does not mention permission requirements or failure modes, which keeps it from a 5.

  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 front-loaded with the main purpose, then provides key outcome details and input requirements in a structured way. It's longer than minimal, but each section adds necessary context for a complex 12-parameter tool.

  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 the tool's complexity, the description covers the core concept, outcome, required/optional inputs, and lifecycle. It lacks detailed parameter semantics and doesn't always connect to schema, but overall it gives sufficient context for correct 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 coverage is only 25%, so the description must compensate. It lists all required and optional parameters and clarifies the tags format (array of {key, value} objects), but does not explain semantics for fields like netTermsDays or fulfillmentTerm, leaving gaps.

  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 creates a new quote (formal order document) for FastSpring SKUs, and distinguishes it from checkout sessions by explicitly saying it does not charge the buyer. It also positions it as the correct way to generate a Custom Order, which differentiates it from the read/update sibling tools.

  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?

  It provides explicit guidance on when to use (to generate a Custom Order/quote) and when not (not a checkout session, does not charge). While it doesn't name an alternative tool, no creation alternative exists among siblings; the exclusion of charging behavior is a clear when-not.

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

• get_subscription_line_itemsA
  4.2/5.0
  Behavior3/5

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

  With no annotations, the description carries the burden of behavioral disclosure. It does explain the required input and return value, but it does not explicitly state whether the operation is read-only, mention authorization requirements, or describe error conditions. The 'Get' and 'Returns' phrasing implies a safe read, but this is not as explicit as it could be.

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

  Conciseness5/5

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

  The description is two concise sentences with no fluff. It front-loads the primary purpose and immediately adds the key prerequisite and return information, making every sentence valuable.

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

  Completeness4/5

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

  For a simple one-parameter getter with no output schema, the description covers the essential aspects: purpose, required input, sourcing instructions, and return values. It lacks only explicit notes on edge cases like empty results or authentication, but these are not critical for basic usage.

  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 coverage is 0%, so the description must compensate, and it does. It explains that subscriptionId is the subscription's internal FastSpring ID and tells the agent exactly where to obtain it (the 'id' field from get_subscription results). This provides meaningful semantics beyond the raw schema, though it does not detail the ID format.

  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 ('Get') and clearly identifies the resource ('products and quantities on a subscription'), distinguishing it from sibling tools like get_subscription. It further clarifies the return content as products, quantities, and SKUs, leaving no ambiguity about its purpose.

  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 gives clear context by stating it requires the subscription's internal FastSpring ID, referencing the 'id' field from get_subscription results. This implicitly tells the agent to first call get_subscription, but it does not explicitly name alternative tools or exclusions, so it falls just short of a 5.

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

• update_order_tagsA
  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 must disclose behavioral traits, and it does: it explicitly warns that tags and item attributes REPLACE existing sets, which is critical for a mutation tool. It also notes that active subscriptions automatically inherit updated attributes. It omits auth/error details but covers the most consequential behaviors.

  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 longer than average but every sentence earns its place, covering purpose, prerequisite, parameter semantics, and a side-effect. It is front-loaded with the main action and structured logically, though it could be trimmed slightly without losing value.

  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 complex mutation tool with nested objects, no annotations, and no output schema, the description provides the essential context: prerequisites, replacement behavior, optionality, and inheritance. It does not describe the response format or error cases, but the invocation-relevant information is clear and sufficient.

  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 only 33%, so the description must compensate. It adds meaning for all three parameters: orderId must be the internal FastSpring ID, tags is a flat key-value map, and items require a product path and an attributes map. It also clarifies that both are optional and highlights the replacement semantics, fully compensating for the schema gaps.

  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 opens with a specific verb and resource: 'Add or replace tags and/or per-product attributes on a FastSpring order.' This clearly distinguishes it from sibling update_subscription_tags by targeting orders, and it names the API endpoint for precision.

  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?

  It explicitly requires the order's internal FastSpring ID from get_order, directing the agent to a sibling tool for prerequisites. It also explains when to use 'tags' vs 'items' and states both are optional, providing clear context without explicitly naming alternatives like update_subscription_tags.

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

• get_subscriptionA
  4.6/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 transparency burden. It discloses that the system checks both current and legacy platforms automatically, and describes the response structure including the 'platform' field. It does not mention error cases or permissions, but for a fetch operation this is adequate.

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

  Conciseness5/5

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

  The description is longer than average but every sentence adds value. It starts with the core purpose, then the platform behavior, then the response fields – structured logically with no fluff.

  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's simplicity (1 parameter, no output schema), the description is remarkably complete. It explains the response with platform-specific fields and even distinguishes modern vs legacy formats, giving an agent full expectations.

  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?

  The schema has 0% description coverage, but the description thoroughly explains the 'reference' parameter as an ID or reference number, provides a concrete example, and clarifies that any identifier is accepted. This fully compensates for the missing schema documentation.

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

  Purpose5/5

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

  The description clearly states the tool's function: 'Fetch a FastSpring subscription by its ID or reference number,' with a concrete example. It distinguishes itself from siblings by focusing on fetching a single subscription by identifier, not listing or line items.

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

  Usage Guidelines4/5

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

  The description implies usage when you have a subscription identifier and need full details. It does not explicitly name alternatives or exclusions, but the context is clear enough for an agent to choose this over list_subscriptions or get_subscription_line_items.

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

• get_orderA
  4.8/5.0
  Behavior5/5

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

  With no annotations provided, the description fully discloses key behaviors: it checks both current and legacy platforms, returns a 'platform' field indicating the source, and details the exact fields present in modern vs. legacy responses. This goes beyond basic fetch semantics and gives the agent precise expectations.

  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 action, followed by useful behavioral and response details. Every sentence adds value, including the breakdown of modern vs. legacy fields, without extraneous information.

  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 there is no output schema, the description effectively explains the return value, including the 'platform' and 'data' fields and their contents. It covers the parameter, platform detection, and field differences, making the tool fully comprehensible 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?

  The input schema only defines 'reference' as a string. The description adds meaning by explaining it accepts ID or reference number and provides an example format. This compensates for the 0% schema description coverage, making the parameter semantics clear.

  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 ('Fetch') and resource ('FastSpring order'). It also specifies the identifier types (ID or reference number) and includes an example format, distinguishing it from sibling tools that list orders or handle subscriptions.

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

  Usage Guidelines4/5

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

  The description implies usage: use when you have an order identifier to fetch a single order. It provides context about dual-platform lookup but does not explicitly mention alternatives or when not to use. This is clear context without exclusions.

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

• update_subscription_tagsA
  4.8/5.0
  Behavior5/5

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

  Without annotations, the description carries the full burden and excels by disclosing that tags REPLACE the full existing set, not merge. It also warns about the need for the internal SBL ID and gives the removal pattern via empty object. This is critical side-effect information for a mutation tool.

  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?

  Four sentences, each earning its place: purpose, prerequisite, behavioral rule, removal method, and API endpoint. The description is front-loaded with the action and avoids any filler or redundancy. Perfectly sized for quick comprehension.

  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 covers prerequisites, parameter semantics, and the crucial replace behavior thoroughly. The API endpoint adds practical context for debugging. For a mutation tool, this is complete enough for correct selection and invocation.

  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?

  The schema only documents the 'tags' parameter's replace behavior, leaving 'subscriptionId' undocumented. The description compensates by identifying 'subscriptionId' as the internal FastSpring SBL ID returned by get_subscription, and for 'tags' reinforces the map structure and full-replacement semantics. This adds significant meaning beyond the schema's 50% 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 verb 'Add or replace' on the specific resource 'FastSpring subscription', and specifies the exact API endpoint. It differentiates from the sibling 'update_order_tags' by targeting subscriptions and explicitly stating the full-replacement semantic. 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?

  Provides strong contextual guidance by requiring the internal FastSpring SBL ID from get_subscription, which tells users they must first fetch the subscription. It also explains the replacement behavior and how to remove all tags, which covers key usage scenarios. It does not explicitly name alternatives like 'update_order_tags', but the resource-specific focus is clear from the purpose.

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