Server Quality Checklist

Tool Scores

• get_full_skillA
  4.4/5.0
  Behavior4/5

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

  Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds valuable behavior beyond that: the tool never raises a protocol error and instead returns an error object, and it shows the typical return shape with an example. The description repeats 'read-only and idempotent' near the end, which is somewhat redundant with the annotations, but the added error-handling context earns a solid score.

  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, followed by a concrete example, usage context, exclusions, and error behavior. It is slightly redundant—'Returns one named skill' restates the first sentence, and the read-only/idempotent claim mirrors the annotations—but overall it is dense and well organized with no wasted sentences.

  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?

  For a read-only retrieval tool, the description is remarkably complete: it specifies the input source, the proper sequencing after preview_product, what it excludes, the output shape with an example, the error-handling contract, and that retrying is safe after correction. The presence of an output schema further reduces the need to document return values. Nothing critical is missing.

  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%, with both params already explained: slug comes from search_catalog and skill_name comes from preview_product's skills list. The description reinforces this with a typical input example but does not add new semantic meaning beyond the schema. Baseline 3 is appropriate when the schema already carries the parameter details.

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

  Purpose5/5

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

  The description opens with a precise verb and resource: 'Load one paid skill's complete instructions from a product.' It immediately distinguishes itself from siblings by stating it is not for the free gateway skill (get_free_skill) and not for all skills at once (get_full_product). An agent can tell exactly what this tool does and what it does not do.

  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 usage context is given: 'Use after preview_product has shown the skill list and the caller wants one specific paid skill.' It also names alternatives and exclusions clearly: 'Not for the free gateway skill...' and 'not for every skill at once (get_full_product).' This gives the agent unambiguous routing guidance.

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

• get_free_skillA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds substantial non-annotation behavior: it returns exactly one skill chosen automatically, requires no plan, never raises a protocol error on bad input, returns a structured error object instead, and is safe to retry after correcting input. This goes well beyond what annotations already provide.

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

  Conciseness4/5

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

  The purpose is front-loaded and most sentences earn their place: use case, sibling comparison, error contract, and retry safety are all relevant. Minor redundancy exists in 'FREE.' and restating read-only/idempotent hints that the annotations already encode, so a small trim would make it even tighter.

  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?

  For a one-parameter read-only tool, this description is complete: it covers input source, a typical request/response shape, the exact selection behavior, the paid-plan boundary, error handling, and idempotent retry safety. An agent has everything needed to invoke it correctly.

  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%, and the schema already documents slug's type, source ('exactly as returned by search_catalog'), and an example. The description's typical-input/output example illustrates the behavior but does not add new parameter-level semantics beyond the schema, so the baseline 3 is appropriate.

  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?

  First sentence states a specific verb, 'load', a specific resource, 'a product's free gateway skill', and the deliverable, 'complete instructions.' It also explicitly distinguishes itself from get_full_skill by saying it is not for the product's other skills, so an agent can tell them apart without opening schemas.

  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 it: 'Use when the caller wants usable instructions immediately.' It also gives the exclusion: other skills need get_full_skill with a skill_name and a paid plan. It even points to search_catalog for the correct slug, leaving no ambiguity about prerequisites or alternatives.

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

• get_full_kitA
  4.6/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint and idempotentHint, and the description adds substantial context beyond them: it warns that the payload is large, notes that the tool requires a PREMIUM plan, and explains the error contract ('never raises a protocol error — it returns {"error": ...}'). This gives the agent clear expectations beyond what annotations provide.

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

  Conciseness4/5

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

  The description is front-loaded with purpose, then gives a concrete example, usage constraints, sibling differentiation, error behavior, and safety guarantees. It is slightly longer than strictly necessary because it repeats read-only/idempotent facts already present in annotations, but every sentence still carries useful guidance.

  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?

  For a single-parameter, read-only tool with an output schema, the description covers all critical invocation context: prerequisites, alternatives, expected output shape, error format, payload size, and retry safety. Nothing important is missing.

  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 and already explains that slug must be 'exactly as returned by list_kits.' The description only repeats this idea with a typical input example, adding little meaningful semantic information beyond the structured 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 opens with a specific verb and resource: 'Load a themed kit and every member product in full.' It further clarifies the scope as 'every member product of one bundle' and explicitly contrasts with get_full_product, making it easy to distinguish from 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 Guidelines5/5

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

  The description gives explicit usage guidance: 'Use only after list_kits has confirmed the kit slug' and 'Not for a single product (get_full_product).' This directly tells the agent when to use the tool and names the alternative, leaving nothing to inference.

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

• preview_productA
  4.6/5.0
  Behavior5/5

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

  Beyond the annotations (readOnlyHint, idempotentHint), the description adds a precise error contract: 'on invalid, missing, or malformed input this tool never raises a protocol error — it returns {"error": ...}'. It also commits to never returning full text and states that retrying after correcting input is always safe. This is valuable behavioral context not present in annotations.

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

  Conciseness4/5

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

  The description is more verbose than strictly necessary but every section earns its place: purpose, example shape, constraint, usage guidance, error behavior, and retry safety. The 'FREE.' fragment adds little value and slightly distracts, but the overall structure is front-loaded and logically organized.

  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?

  For a single-parameter read-only tool, this description is complete: it explains what it returns, what it never returns, how errors behave, and which sibling tools cover the excluded cases. The output schema and the inline example round out the return contract. No critical context is missing.

  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 already provides 100% coverage with a clear slug description ('Product slug exactly as returned by search_catalog or recommend_products, e.g. "inbox-zero-assistant"'). The description reinforces this with a typical input example but adds no new semantic meaning beyond the schema. Baseline 3 is appropriate.

  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: 'Preview one product: metadata, persona teaser, and paid-skill teasers.' It clearly distinguishes itself from full-content tools by stating 'Returns teasers only, never full text.' This is unambiguous and uniquely identifies the tool's role.

  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 explicitly says when to use it ('Use to judge a product before committing') and when not to ('Not for the complete persona or skill bodies (get_full_persona, get_full_product), and not when the caller wants instructions they can act on now (get_free_skill)'). It names the exact sibling alternatives, leaving no inference required.

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

• recommend_productsA
  4.6/5.0
  Behavior5/5

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

  Annotations already cover read-only and idempotent hints, but the description adds meaningful behavior beyond them: it never raises a protocol error and instead returns an error object with remediation guidance. It also reveals the ranking-by-fit behavior and the output shape, giving an agent accurate expectations for a call.

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

  Conciseness4/5

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

  The description is well-structured and front-loaded with the core purpose, followed by a concrete example, usage guidance, and error behavior. It is slightly redundant by repeating read-only and idempotent facts already stated in annotations, but each sentence otherwise earns its place.

  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 moderate complexity, a full output schema, and rich annotations, the description covers everything needed to select and call it correctly: purpose, typical input/output, when to use an alternative, error handling, and safety of retry. Nothing important is missing.

  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 100% and the schema already documents both parameters, including the clamp behavior for limit and an example for need. The description reinforces those semantics with a typical input/output example but does not add substantial meaning beyond the schema, so the baseline 3 applies.

  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?

  States a specific verb ('Recommend'), resource ('catalog products'), and the input mode ('need described in plain language'). It also distinguishes itself from search_catalog by explicitly noting it is not for exact keyword or slug lookups, so an agent can tell siblings apart.

  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 says when to use ('when the caller describes a problem instead of naming a product'), how ranking works (by fit to the described need), and names the alternative for exact lookups (search_catalog). This leaves no ambiguity about selection versus siblings.

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

• get_full_personaA
  4.7/5.0
  Behavior5/5

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

  The annotations already mark the call read-only and idempotent, and the description adds valuable behavior beyond that: it guarantees no protocol error on invalid input, instead returning an error object with a fix hint, and it documents the exact response shape with a typical example. The premium plan signal is also useful context not present in annotations.

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

  Conciseness5/5

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

  The description is structured with a one-line summary, an illustrative example, explicit scope guidance, an error contract, and a retry safety note. Every sentence conveys useful information; the wording is tight and the most decision-relevant facts are front-loaded.

  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?

  For a single-parameter read-only tool with an output schema, this description is complete: input source, expected output, error format, usage boundaries, sibling alternative, and premium requirement are all covered. There is no obvious missing context an agent would need to call it correctly.

  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 100%, and the schema already states that slug is 'Product slug exactly as returned by search_catalog.' The description reinforces this with a concrete example, but it does not add meaning beyond what the input schema already provides, so the baseline 3 is appropriate.

  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 states a specific verb and resource: 'Load a product's complete persona definition' and clearly differentiates this tool from siblings by saying it returns 'the persona text alone, with no skill bodies.' It also names get_full_product as the alternative that includes skills, so an agent can distinguish them without opening schemas.

  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 explicitly says when to use this tool: when the caller needs 'the product's voice and operating rules only' and when not to use it: 'Not when skills are also wanted - get_full_product returns persona and every skill in one call.' It also flags premium plan availability, which helps the agent decide within plan constraints.

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

• get_full_productA
  4.8/5.0
  Behavior5/5

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

  Annotations already mark read-only and idempotent, but the description goes beyond them by detailing the exact error behavior: 'never raises a protocol error — it returns {"error": ...}' with an example. It also adds the practical consequence of idempotency—'after correcting the input it is always safe to retry'—and the PREMIUM access constraint, none of which are present in annotations.

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

  Conciseness4/5

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

  The description is front-loaded with the core purpose and is organized into clear segments: purpose, premium note, example, use cases, and error handling. It is slightly repetitive ('Load one product in full' and 'Returns persona plus every skill for one product' say the same thing), but every other sentence earns its place.

  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?

  For a single-parameter tool with full schema coverage, annotations, and an output schema, the description covers everything an agent needs: what it returns, when to use it, how errors are surfaced, retry safety, and the premium requirement. No critical behavioral or usage information is missing.

  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 100%, with slug described as 'Product slug exactly as returned by search_catalog.' The description adds a concrete example input ('{"slug": "inbox-zero-assistant"}') and shows the expected shape of a successful response, which helps agents understand how the slug parameter maps to behavior beyond the schema's bare definition.

  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: 'Load one product in full: persona plus every skill's instructions.' It explicitly differentiates from siblings by stating it is not for a single skill (get_full_skill) and not for a bundle of products (get_full_kit), making the tool's unique scope unmistakable.

  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 gives a direct usage condition: 'Use when the caller wants the whole product.' It also names exclusions and alternatives, instructing agents to use get_full_skill for a single skill and get_full_kit for a bundle. The premium plan note adds a prerequisite, further clarifying when this tool applies.

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

• list_kitsA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds substantial behavioral context: no arguments, exact return object shape with fields, error behavior ('never raises a protocol error — it returns {"error": ...}'), and retry safety. These details go well beyond the structured annotations.

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

  Conciseness5/5

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

  Every sentence carries necessary information: purpose, free access, no-argument requirement, return format, routing guidance, error contract, and idempotence. The most important usage guidance is front-loaded after the first sentence. No filler or redundancy.

  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?

  For a zero-parameter read-only tool with an output schema, the description is fully complete. It covers purpose, return structure, usage boundaries versus siblings, error handling, and retry behavior. Nothing an agent needs to call this tool correctly is missing.

  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 the baseline is 4. The description reinforces this with 'Takes no arguments,' which eliminates any guesswork. Since there are no parameters to explain, the description adds all the clarity needed.

  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: 'List the 12 themed kits with pricing and member products.' It clearly differentiates from siblings by noting that get_full_kit is for a kit's full contents and search_catalog is for individual products.

  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: 'Use when the caller asks about bundles or bundle pricing.' It also gives direct exclusions: 'Not for individual products (search_catalog) and not for a kit's full contents (get_full_kit).' This leaves no ambiguity about when to select this tool over alternatives.

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

• search_catalogA
  4.9/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, and the description adds valuable behavioral detail beyond those: it never raises a protocol error but returns an {'error': ...} object with remediation, every call is safe to retry, and an empty query with an area browses that area. This gives the agent clear expectations for abnormal input without contradicting the annotations.

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

  Conciseness5/5

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

  The description is front-loaded with the core action, followed by a compact example, usage rule, exclusions, and error behavior. Every sentence adds distinct value; there is no filler or repetition beyond what annotations already provide.

  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 three optional parameters, a full input schema, an output schema, and annotations covering read-only/idempotent behavior, the description fills the remaining gaps: exact error semantics, result shape, usage boundaries, and browsing behavior. An agent has everything needed to select and invoke this tool correctly.

  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 100%, so the schema carries the basic parameter definitions. The description adds meaning beyond the schema by showing a typical input object, clarifying that query matches name/tagline/slug/segment in context, and explaining the empty-query-with-area browsing behavior. This exceeds the baseline for well-covered schemas.

  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 states a specific verb and resource ('Search all 138 catalog products by keyword and/or focus area') and immediately distinguishes itself from siblings by saying what it is not for: bundles (list_kits) and plain-language problem statements (recommend_products). The example input/output makes the purpose unmistakable.

  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 gives explicit when-to-use guidance: 'Use when the caller names a keyword, product, or focus area to look up.' It also gives explicit when-not-to-use guidance with named alternatives: not for bundles (list_kits) and not for problem statements (recommend_products ranks by fit). This is exactly the level of routing an agent needs.

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

• upgrade_infoA
  5/5.0
  Behavior5/5

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

  Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, but the description adds meaningful behavioral context beyond them: it never raises a protocol error on invalid/missing/malformed input and instead returns an error object. It also states that every call is read-only and idempotent, making retry safety explicit.

  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 ('Explain how to unlock full personas, paid skills, and kits'), then moves to return shape, usage context, exclusions, and error behavior. Each sentence earns its place and the structure is logically ordered.

  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?

  The description covers the return shape, the exact use case, exclusions, error behavior, and safety profile. There is an output schema, but the description still explains the key return fields and retry semantics. Nothing an agent needs to call this tool correctly is missing.

  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 tool has zero parameters, and the description explicitly says 'Takes no arguments.' It also explains that invalid or malformed input will yield a structured error response, which is useful even for a no-argument tool. Since the schema is empty, this description fully covers parameter 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 states a specific verb and resource: 'Explain how to unlock full personas, paid skills, and kits.' It also clearly differentiates from siblings by explicitly excluding per-bundle or per-product pricing and naming list_kits and preview_product as the alternatives. An agent can recognize exactly what this tool is for without opening schemas.

  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 explicit when-to-use guidance: 'Use when a premium tool has been refused or the caller asks what a plan covers.' It also states what it is not for, naming sibling tools list_kits and preview_product. This fully routes the agent between alternatives.

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