SuppCo

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

Annotations already declare non-idempotent, non-readonly, non-destructive behavior; the description adds concrete meaning by explaining the accumulation semantics ('calling it again adds more units') and the subscription behavior at the recommended shipping interval. It also notes the cart is the same as the SuppCo app, but omits any auth/permission requirements.

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

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

Front-loads the action and target, then layers in input sourcing, the subscription flag, return value, and the accumulation caveat with its alternative. Every sentence carries information and none is redundant.

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

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

An output schema exists, so the description need not detail the returned cart; it still mentions 'Returns the updated cart.' Combined with full parameter coverage and sibling routing, nothing an agent needs to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description earns extra by clarifying that subscription routes to the product's recommended shipping interval and that product_id_or_slug must resolve to a Buying Club product. That adds meaning beyond the schema's terse field notes.

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

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

Specific verb ('Add') plus resource ('a Buying Club product to the signed-in user's cart') with explicit scope ('only Buying Club products can be added'). It clearly distinguishes itself from sibling cart tools and names the discovery tools that provide valid inputs.

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

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

States where to get inputs (suppco_find_buying_club_products, suppco_compare_to_buying_club) and explicitly names the alternative for a different intent ('to set an exact quantity, use suppco_update_cart_item'). When-to-use and when-to-use-something-else are both covered.

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

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

Annotations already declare non-read-only, non-idempotent, non-destructive, closed-world behavior. The description adds genuinely new context: the target is the signed-in user's stack (implying auth scope), the operation has no purchasing side effect, and the id originates from a search/product result. It does not warn about duplicate entries despite idempotentHint=false, which is the one remaining gap.

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

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

Four tight clauses front-loaded with the usage trigger, then the action, then parameter sourcing, then the boundary against the cart tool. No sentence is redundant.

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

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

For a single-parameter, no-output-schema write tool this is nearly complete: intent, auth scope, parameter sourcing, and the cart boundary are all covered. Only duplicate/idempotency behavior and the resulting state change are left unstated.

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

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

Schema coverage is 100% but the schema text is terse ('SuppCo Product ID'). The description adds real value by specifying the accepted formats (UUID or slug) and where to source the value (a search or product result), which the schema does not say.

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

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

States a specific verb+resource ('Adds the product to the ... user's stack') and immediately separates itself from the nearest sibling by clarifying it is tracking, not purchasing. An agent can distinguish it from suppco_add_to_cart, suppco_remove_from_stack, and suppco_manage_stack without opening a schema.

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

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

Gives an explicit when-to-use trigger ('when the user wants to start tracking a product') and an explicit when-not with a named alternative ('this does not buy anything; to buy a Buying Club product, use suppco_add_to_cart'). The routing decision is fully resolved in the text.

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

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

Annotations already declare readOnly/idempotent/non-destructive, so safety is covered; the description adds the meaningful behavioral detail that the response pairs the anchor product's trust score, ingredients and excipients with a filtered set of alternatives. It does not state how many alternatives are returned or whether results are capped/paginated.

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

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

Three tight sentences, front-loaded with the action, then the return shape, then the usage trigger – no filler. The middle sentence's 'filtered alternatives' is slightly vague about what the filter is, but nothing is wasted.

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

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

With no output schema, the description does take on describing the return payload and does so at a useful level. Given six parameters with one required and rich schema-level documentation, the only residual gap is result cardinality/ordering behavior for the alternatives list.

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

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

Schema description coverage is 100%, so all six parameters, including the enum and the priority/certifications profile-default behavior, are already documented in the schema. The description adds no parameter-level meaning beyond that, which is the expected baseline when the schema does the heavy lifting.

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

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

States a specific verb+resource ('compare a product against alternatives in its category') and adds the scope of what comes back (anchor product trust score, ingredients, excipients). It is clearly separable from suppco_get_product_info and suppco_find_products, but it never addresses the nearby sibling suppco_compare_to_buying_club, which an agent could plausibly confuse it with.

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

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

Gives concrete triggering intents: 'compare', 'find alternatives', or 'is there something better?' – enough for an agent to route on user phrasing. It stops short of exclusions or naming an alternative tool when the user wants a plain product lookup or a buying-club comparison.

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

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

The annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so the description only needs additive context — and it delivers that by describing the return payload (source product plus same-category Buying Club items with TrustScore, price, member price, cashback), which matters since there is no output schema.

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

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

Two sentences, zero waste: the usage trigger is front-loaded and the return content follows. Nothing is padded or repeated from structured fields.

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

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

For a read-only comparison tool with rich annotations and no output schema, the description supplies the trigger plus the return shape an agent needs. Minor gaps (no pagination/limit behavior, no explicit sibling routing) keep it from full marks.

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

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

Schema description coverage is 100%, so all six parameters are self-documented and the baseline is 3. The description adds no syntax or filtering semantics beyond hinting product_id_or_slug is usually an existing user product.

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

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

States a specific verb (compare) and resource (Buying Club) scoped to 'a specific product.' It is clear, but it never names or distinguishes itself from the close sibling suppco_compare_product_to_alternatives, so an agent cannot fully disambiguate the two from the description alone.

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

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

'Use this when the user asks whether the SuppCo Buying Club carries an alternative to a specific product' gives explicit trigger conditions and even notes the typical input ('usually one they already take'). It stops short of exclusions or naming the alternative tool (compare_product_to_alternatives) that handles non-Buying-Club comparisons.

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

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 fully covered elsewhere and the bar is lower. The description's only behavioral contribution is framing itself as a search/list tool with an optional filter, which adds little beyond what the annotations and schema already convey; it says nothing about result count limits, pagination, or how TESTED status affects ordering.

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

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

Two short sentences, front-loaded with the action and then the usage. The opening 'Find and filter brands' is partially restated by the second sentence, which is minor redundancy rather than waste.

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

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

For a simple, zero-required-parameter read-only search tool with full schema coverage, no output schema needed, and strong annotations, the description covers what the agent needs to select and call it. Only the missing routing guidance against sibling brand tools keeps it short of complete.

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

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

Schema description coverage is 100%, so both parameters (name, tested) are already documented at a level the description does not exceed. The description hints at the naming and filtering use of both parameters but adds no format, matching, or partial-name semantics beyond the schema.

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

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

The description states a specific verb (find/filter) and resource (brands), and the object name plus title reinforce it. It distinguishes itself from suppco_find_products by staying strictly on brands, though it never explicitly contrasts with suppco_get_brand_trust_score, which is the nearest-looking sibling.

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

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

It gives two usage modes (search by name, list by criteria) and an example filter, which implies when to call it. However, it names no alternatives and sets no exclusions, so the agent must infer whether to use this versus find_products or get_brand_trust_score for brand discovery.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds meaningful domain behavior: results carry member pricing and earnings credit (cashback), which is not in any structured field. It stops short of describing pagination behavior or result ordering mechanics beyond the priority parameter.

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

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

Three sentences, front-loaded with the core capability, then usage context, then the routing rule. Minor redundancy in the cashback/member-pricing clause, but no sentence is wasted.

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

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

For an 11-parameter search tool with no output schema, the description covers purpose, both search modes, and the sibling routing decision, which is what an agent needs to pick the right tool. It omits any mention of paging through results or result-count limits, though those are documented in the schema.

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

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

Schema description coverage is 100%, so all 11 parameters are already documented with examples, valid values and defaults. The description only restates the filter families (category, trust, price, form, certifications, brand) without adding syntax or edge-case semantics 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.

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

The description states a concrete verb ('search/browse') and resource ('SuppCo buying club catalog') and describes both operating modes (free-text query vs. filtered browsing). It explicitly distinguishes itself from the sibling suppco_compare_to_buying_club, so an agent can route correctly without opening the schemas.

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

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

It states the positive condition ('when the user is exploring a category with no specific current product in play') and names the alternative plus why it wins ('suppco_compare_to_buying_club returns their current product as the anchor'). That is explicit when-to-use and when-not-to-use guidance.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false, so the safety profile is fully covered by structured data. The description adds nothing behavioral on top of that — no mention of pagination via limit/offset, of the profile-driven defaults for priority and certifications, or of result ranking. It is essentially a restatement of the name.

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

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

Two short sentences with the verb-resource front-loaded and no padding. The 'handles search, browsing, and recommendations' clause is somewhat generic filler, but overall the definition is efficiently sized.

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

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

This is a 13-parameter discovery tool with two distinct modes (free-text query vs category+filters), 0 required params, and no output schema or annotation coverage of the mode split. The description never mentions the required product_category_name for filtered searches or the profile-default behavior of priority/certifications, leaving the agent reliant entirely on schema text.

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

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

Schema description coverage is 100% across all 13 params, including the detailed query-vs-product_category_name rule, the priority enum, and profile-override semantics for certifications. The description contributes no parameter 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.

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

States a specific verb+resource ('Find products') and broadens scope to search, browsing, and recommendations, which separates it from read-only siblings like suppco_get_product_info or suppco_find_brands. It stops short of naming any sibling as the alternative, so the boundary with find_buying_club_products/find_brands is left implicit.

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

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

'Use this whenever the user wants to discover or find products' gives an always-on trigger but no when-not condition and no alternatives. Critically, the schema's own rule that query must not be combined with filters (and that product_category_name is required for filtered searches) is never surfaced in the description, so the agent gets no routing guidance for the tool's two distinct modes.

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

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

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=true and destructiveHint=false, so the safety and idempotency profile is fully covered. The description adds the return content ('TrustScore with its quality assessment') but says nothing about behavior on an unknown brand or how ambiguity in name/slug/UUID is resolved. With annotations carrying the load, a 3 is appropriate.

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

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

Three tight sentences: usage trigger first, then the returned value, then the argument. The trigger is front-loaded and no sentence is padding, though the parameter sentence is largely redundant with the schema.

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

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

For a single-lookup read tool with 100% schema coverage and full annotations but no output schema, the description tells the agent what it gets back and how to invoke it. Only the not-found / ambiguous-query behavior is left unspecified, which is a minor gap.

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

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

Schema description coverage is 100%, and the description's parameter sentence ('Pass the brand's name, slug or UUID as brand_query') merely restates what the schema already documents, including the accepted identifier forms. It adds no syntax, precedence, or ambiguity-resolution detail 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.

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

States a specific verb+resource: returns the brand's TrustScore with its quality assessment, and the trigger condition (user asking how trustworthy a brand is) makes the intent unambiguous. It distinguishes itself from suppco_get_product_trust_score implicitly via 'brand' vs product, but never names that sibling explicitly, so it falls short of a 5.

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

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

The opening clause gives a concrete when-to-use condition ('when the user asks how trustworthy or high-quality a specific supplement brand is'). It offers no exclusions or routing to alternatives such as suppco_find_brands or suppco_get_product_trust_score, so it is clear context without the when-not guidance that would earn a 5.

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

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

Goes well beyond the annotations by disclosing traits annotations cannot express: the link signs the user into checkout, it is single-use ('works once'), and it expires after 10 minutes. These are exactly the constraints an agent must respect to avoid handing the user a dead link, and they are consistent with the non-idempotent, non-read-only annotations.

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

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

Four sentences, zero filler: purpose first, then the sign-in/credit mechanics, then the single-use/expiry constraint paired with the usage condition, then the parameter caveat. Every sentence carries decision-relevant information.

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

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

With an output schema present, return format need not be described, and safety/permission behavior is covered by annotations plus the expiry and single-use disclosure. Nothing an agent needs in order to call this correctly is missing.

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

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

Schema coverage is 100%, so the baseline is 3; the description adds real meaning by stating that Buying Club credit is applied by default and naming the exact opt-out condition ('set use_wallet to false if the user doesn't want to use their credit'). That is more than a restatement of the schema's default note.

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

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

States a specific verb and resource ('Get a secure checkout link for the signed-in user's cart') and is instantly separable from sibling cart tools like suppco_get_my_cart and suppco_add_to_cart, since a checkout URL is a distinct artifact. The added clause about sign-in for member pricing clarifies the resource's nature rather than restating the name.

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

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

Gives an explicit when-to-use condition ('call this only when the user is ready to pay and give them the link right away') plus a default-behavior caveat for use_wallet. It does not name a sibling alternative or a precondition such as needing items in the cart, so it falls just short of the 5 bar.

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

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 fully covered. The description adds domain context (credit, cashback, unavailable items) but no auth, rate-limit, or freshness behavior beyond that.

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

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

A single front-loaded sentence leading with the verb and resource, followed by a tight enumeration of contents. No filler or redundant restatement of the title.

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

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

With an output schema present, the description needn't spell out return values, and it correctly avoids doing so beyond a high-level summary. For a zero-param read tool with rich annotations, it is complete enough.

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

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

The tool takes zero parameters and schema description coverage is 100%, so there is nothing for the description to clarify. Baseline 4 applies for a no-argument tool.

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

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

States a specific verb ('Get') and resource (the signed-in user's Buying Club cart) and enumerates exactly what the cart contains. This cleanly separates it from the cart-mutation siblings (add_to_cart, remove_from_cart, update_cart_item) without needing to name them.

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

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

Usage is implied by the read nature and the 'signed-in user' scoping, but the description never states when to reach for this versus get_checkout_url or the stack/protocol siblings, nor any exclusion. It's adequate but leaves routing to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the plan is scoped to the signed-in user and what the payload contains, which is useful, but says nothing about edge cases such as an unconfigured/empty plan.

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

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

Two tightly written sentences: trigger condition first, payload second, sibling disambiguation last. No filler, no repetition of the title.

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

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

With no output schema, the description carries the burden of describing the return, and it does so at a usable level ('personalized plan with recommended nutrients and dosages'). It omits what happens when the user has no plan or profile data, which is the only remaining gap for a zero-param read tool.

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

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

The tool takes zero parameters, so there are no parameter semantics to document and the baseline of 4 applies. Nothing in the description is needed to clarify inputs.

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

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

States a specific verb and resource ('Returns the signed-in user's personalized plan with recommended nutrients and dosages') and explicitly differentiates itself from the closely named sibling suppco_get_my_nutrient_totals. An agent can select between them without opening either schema.

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

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

Gives an explicit trigger ('when the user asks which nutrients they should take or how much') and names the alternative plus the condition that selects it ('current stack actually provides' → suppco_get_my_nutrient_totals). This is exactly the when-to-use/when-not pattern.

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

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 that it aggregates the signed-in user's stack against recommended values, which is useful, but it says nothing about granularity (per-nutrient vs overall), empty-stack behavior, or freshness — and there is no output schema to fall back on.

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

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

Two sentences with no waste: the first front-loads the usage trigger and the second states what the call returns. Sized appropriately for a zero-parameter read tool.

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

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

For a no-arg, read-only tool with no output schema, the description conveys the essential shape of the result (daily totals vs recommended amounts). Minor gaps remain around result granularity and behavior when the stack is empty, but nothing blocks correct invocation.

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

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

The tool takes zero parameters, so the baseline is 4 and there is no ambiguity for the description to resolve. Nothing misleading is stated about inputs.

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

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

Names a specific verb+resource ('Returns the daily nutrient totals from the signed-in user's stack') and specifies the comparison against recommended values. It is clear on its own, but it does not distinguish itself from close siblings like suppco_get_my_nutrient_plan or suppco_get_my_stack, so an agent must infer the boundary.

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

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

Gives an explicit trigger ('Use this when the user asks how much of a nutrient their current supplements provide, or whether they are over or under recommended amounts'). That is strong when-to-use guidance, though it names no alternative or exclusion to route against the nutrient-plan and stack tools.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and closed-world, so the safety profile is covered. The description adds useful context beyond that: the result is scoped to the signed-in user (implying auth/session state) and includes progress plus supplement recommendations. It does not describe pagination or freshness, so it stops short of 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.

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

Two sentences, zero waste, with the trigger condition front-loaded and the sibling routing at the end. Every clause earns its place.

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

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

With no output schema, the description must preview the return payload, and it does so at a high level ('protocols with progress and supplement recommendations'). That is sufficient for an agent to decide to call it, though exact field shape remains unspecified.

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

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

The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. No parameter-level detail is needed or missing.

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

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

States a specific verb+resource ('Returns the signed-in user's protocols') scoped to the caller's own data, and explicitly distinguishes itself from suppco_search_protocols. An agent can route between discovery and retrieval without opening any schema.

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

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

Gives an explicit trigger condition ('when the user asks about the health protocols they are following') and names the alternative tool with the condition that selects it ('To find new protocols, use suppco_search_protocols'). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and closed-world scope, so the safety profile is covered. The description adds genuine value by disclosing the returned content (time slots, dose amounts per slot, with_food flags, frequency), which matters because there is no output schema. It stops short of 5 by omitting any mention of pagination or shape limits, though for a personal schedule these are minor.

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

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

A single sentence that front-loads the purpose and then enumerates the return payload with no filler. Every listed item earns its place given the absence of an output schema.

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

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

For a no-parameter read tool with full annotation coverage but no output schema, the description supplies enough about the returned structure for an agent to use the result. A note on how to modify the schedule (suppco_update_product_schedule) would close the remaining gap.

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

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

The tool takes zero parameters, so the baseline is 4. The description correctly implies no inputs are required to fetch the user's own schedule, and nothing in the schema needs compensating for.

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

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

States a specific verb and resource ('Get the user's current supplement schedule') and enumerates exactly what the schedule contains — time slots, per-slot doses, with_food flags, frequency. It does not explicitly distinguish itself from nearby siblings like suppco_get_my_stack or suppco_get_my_protocols, so it stops short of a 5.

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

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

Read usage is implied by 'current schedule', but there is no statement of when to call this versus suppco_get_my_stack, suppco_get_my_protocols, or the mutating suppco_update_product_schedule. No prerequisites or exclusions are given, leaving the agent to infer the routing.

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

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

Annotations already declare readOnlyHint, idempotentHint and destructiveHint=false, so the safety profile is covered. The description adds meaningful context beyond that: the return payload contains every product with dosages, daily totals, and the product IDs that other SuppCo tools accept, which tells the agent this is a dependency-resolution read.

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

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

Two tight sentences that lead with the usage trigger and follow with the payload contents. The 'recommending, comparing, swapping or removing' list is mildly enumerative but each item signals a real downstream workflow, so it mostly earns its place.

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

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

With no output schema, the description carries the burden of describing returns and does so well: full product list, dosages, daily totals, and reusable product IDs. For a zero-parameter read tool with rich annotations, nothing an agent needs to call it correctly is missing.

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

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

The tool takes zero parameters, so the schema baseline is 4. The description correctly implies no inputs are needed (it operates on the signed-in user) and adds no misleading parameter expectations.

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

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

States a specific verb+resource ('signed-in user's current supplements') and immediately scopes the resource as the user's stack with dosages and daily totals. It is clearly distinguishable from sibling getters like suppco_get_my_cart, suppco_get_my_nutrient_plan, and suppco_get_my_protocols.

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

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

Explicitly says when to use it ('before recommending, comparing, swapping or removing products'), which maps to concrete workflows involving siblings like suppco_swap_products and suppco_remove_from_stack. There is no when-not guidance or named alternative, so it falls 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.

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds real value beyond that by scoping the tool's limits: general information only, no diagnosis/treatment, no personalized dosing advice. It does not disclose return format or citation behavior, which keeps it short of 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.

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

Three sentences, front-loaded with the trigger condition, then the output contents, then the disclaimer and the sibling routing. Every sentence carries information an agent needs; nothing is padding.

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

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

With no output schema, the description compensates by enumerating what comes back (intake ranges, upper limits, timing, food guidance, graded research summary). Combined with the scope disclaimer and the routing pointer, an agent has everything needed to select and call this tool correctly.

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

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

Schema description coverage is 100% and the single parameter already documents itself with concrete examples ('Vitamin D3', 'Magnesium', 'Fish Oil'). The description only restates the parameter as 'a specific nutrient or supplement', adding no syntax, aliasing, or format guidance beyond the schema, so baseline 3 applies.

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

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

Names a specific verb+resource and enumerates exactly what 'nutrient info' contains: typical daily intake ranges, upper limits, timing, food interactions, and a graded research summary. It also explicitly distinguishes itself from the sibling suppco_search_effects, so an agent can route without opening either schema.

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

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

Opens with an explicit trigger ('Use this when the user asks about dosing for a specific nutrient or supplement') and names the alternative with the condition that selects it ('For what studies say about a supplement for a specific health area, use suppco_search_effects'). Both when-to-use and when-to-use-something-else are covered.

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

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

Annotations already declare readOnly, idempotent, open-world, non-destructive, so the safety profile is fully covered without the description. The description adds the useful behavioral note that names are accepted when no id exists, implying fuzzy resolution, but says nothing about ambiguity, failures for unmatched names, auth, or rate limits. Adequate 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.

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

Three tight sentences, front-loaded with purpose and returned fields before the alternative-tool routing. No filler phrases and nothing redundant with the schema beyond a brief identifier recap.

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

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

With no output schema present, the description compensates by naming the returned fields, and it covers identifier formats, batching, and sibling routing for a one-parameter read tool. An agent has everything needed to call this correctly.

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

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

Schema description coverage is 100% and the single parameter is fully documented there, including the max-5 limit, the ' | ' string form, and the preference for previously obtained ids. The description restates rather than extends this, so the baseline 3 applies.

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

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

States a specific verb (look up) and resource (product info) and enumerates the returned fields (composition, ingredients, price, format, servings) plus the accepted identifier types (UUID, slug, name). It explicitly names the sibling it is not for trust data, suppco_get_product_trust_score, so an agent can distinguish it without opening either schema.

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

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

Gives concrete triggering scenarios ("tell me about <product>", hydrating ids from the user's stack) and an explicit exclusion routing to suppco_get_product_trust_score for TrustScore rationale, certifications, and testing. The name-vs-id fallback is also clarified.

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

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

Annotations already declare readOnly, idempotent, openWorld and non-destructive, so the safety profile is covered. The description adds real behavioral context beyond that: it discloses the depth of data returned versus sibling tools and that multiple identifiers are accepted in a single call, which shapes how an agent batches requests.

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

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

Three sentences, front-loaded with purpose, then when-to-use, then the differentiator. The identifier sentence mildly duplicates the schema but is short. Almost no wasted text, though the middle sentence could be tightened.

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

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

With no output schema, the description carries the burden of describing returns, and it does so by enumerating the specific content categories an agent will get back. Combined with the when-to-use guidance, an agent has enough to call and interpret it; only the batch/response shape is left implicit.

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

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

Schema description coverage is 100% and the single parameter is fully documented in the schema, including accepted ID types, the max of 5, and the ' | ' separator. The description only restates 'Accepts product ids/slugs/names (multiple)', adding no syntax or formatting detail beyond the schema, so the baseline of 3 applies.

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

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

The description opens with a specific verb+resource ('Get TrustScore details and quality assessment for one or more products') and then enumerates the concrete contents (rationale, certifications, lab results, brand practices, excipient risk). It clearly distinguishes itself from siblings by noting 'the other product tools return only the headline score number.'

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

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

It gives explicit when-to-use guidance ('Call this before discussing why a product is (or is not) trustworthy, its certifications, or its testing') and contrasts with the alternative class of tools. It does not name the specific sibling (e.g. suppco_get_product_info) that returns the headline score, so routing is slightly less precise than it could be.

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

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

Annotations already declare readOnlyHint/idempotentHint/destructiveHint=false, so the safety profile is covered. The description adds useful content context — that the response carries four rating dimensions and coaching recommendations — though it omits whether the score is cached or computed on demand, which matters given the sibling refresh tool.

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

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

Three sentences, front-loaded with the usage trigger, then return contents, then the filter hint. Efficient overall; only the final 'Pass category to get a single category' sentence is mildly redundant given the schema.

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

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

With no output schema, the description is right to name the returned rating dimensions and recommendations, and the single optional enum parameter is fully covered by the schema. The only missing piece is the read-vs-refresh relationship with suppco_refresh_stack_score.

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

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

Schema description coverage is 100% and the enum values are documented in the schema itself. The line 'Pass category to get a single category' simply restates the schema with no added syntax, defaults, or interaction detail, so the baseline of 3 applies.

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

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

Names a specific verb+resource ('returns the signed-in user's StackScore') and enumerates exactly what the score comprises (Quality, Value, Goals, Dosage ratings plus coaching recommendations). This cleanly separates it from siblings like suppco_get_my_stack or suppco_refresh_stack_score.

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

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

Gives a concrete trigger: 'Use this when the user asks how good their supplement stack is or how to improve it.' That is clear context, but it never mentions the adjacent suppco_refresh_stack_score, so the agent gets no guidance on when to read a score versus trigger a recomputation.

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

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

Annotations already declare destructiveHint=true, idempotentHint=false and a non-read-only profile, so the safety burden is largely covered. The description adds the useful behavioral fact that input is free-form natural language and that the tool is deprecated, but says nothing about confirmation, partial-failure, or what exactly a swap destroys. Moderate added value against low annotation burden is a 3.

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

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

Two sentences, ~25 words, with the deprecation/routing guidance front-loaded ahead of the capability statement. Every clause earns its place and nothing is padded.

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

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

For a single-parameter, no-output-schema, fully annotated tool, this covers purpose, routing, and input style adequately. It stops short of explaining what the agent sees back after a mutation or how conflicts in a free-text command are resolved, which is a minor remaining gap.

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

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

There is only one parameter and schema description coverage is 100%, with the schema already supplying example strings ('add thorne-vitamin-d-k2', 'swap thorne-creatine for momentous-creatine'). The description restates the natural-language input style but adds no syntax, naming, or format constraint 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.

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

It states a specific verb set and resource ('Add, remove, or swap products in user's supplement stack') and explicitly distinguishes itself from the very siblings it overlaps with (add_to_stack, remove_from_stack, swap_products). An agent can decide whether this legacy tool or a specific sibling applies without opening any schema.

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

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

The first sentence is an explicit routing instruction: 'Legacy: prefer suppco_add_to_stack / suppco_remove_from_stack / suppco_swap_products.' It names the exact alternatives by tool id and tells the agent when not to use this tool, which is the strongest form of usage guidance.

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

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

Annotations declare the non-idempotent, non-read-only profile, and the description adds genuinely new context: the recalculation is asynchronous and takes a few minutes. It doesn't say what the agent should do while waiting or whether repeated calls queue/stack, so it stops short of 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.

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

Three short sentences, zero filler, and the most important fact (this triggers an async refresh) is front-loaded ahead of the confirmation constraint.

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

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

For a zero-parameter, no-output-schema trigger action, the description supplies the essentials: what fires, that it's async with a multi-minute latency, and the confirmation precondition. Only the post-trigger expectation (e.g., poll get_stack_score) is left unstated.

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

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

Zero parameters, so the schema has nothing to document and the description is not expected to explain parameter semantics. Baseline 4 applies.

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

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

States a specific verb and resource: 'Kick off a StackScore refresh.' The action semantics (trigger a recalculation) are clearly distinct from the read-only sibling suppco_get_stack_score, though no sibling is named explicitly.

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

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

Gives an explicit gating condition: 'Only use when the user confirms they want to refresh.' This is a real when-to-use rule. It stops short of naming the alternative (get_stack_score) for agents that just want to read the existing score.

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

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

Annotations only flag this as destructive/idempotent; the description adds the crucial blast radius – removing a product deletes every cart line for it, both one-time and subscription, not just one line. It also states the signed-in-user cart scope and that an updated cart is returned, which annotations cannot convey.

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

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

Three sentences, front-loaded with the primary action, then the alternate mode, then the side-effect and return. No filler; every clause carries information an agent needs.

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

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

Covers scope (signed-in user's cart), both modes, destructive blast radius, and the return value, while an output schema exists for the returned cart. Nothing material is missing for correct invocation.

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

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

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning beyond the schema: it clarifies that product_id_or_slug removal acts on all matching cart lines (one-time and subscription), which the schema's 'product to remove' wording leaves ambiguous.

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

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

States a specific verb (remove) and resource (product from the signed-in user's cart), plus a second mode (clear unavailable items). An agent can distinguish this from suppco_add_to_cart, suppco_update_cart_item, and suppco_get_my_cart without opening any schema.

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

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

Gives a clear conditional for the remove_unavailable mode ('set remove_unavailable to true to clear items that are no longer available'), which covers two distinct use cases. It does not, however, name an alternative for partial edits (e.g., suppco_update_cart_item for quantity changes) or state when not to remove.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the agent knows this is a non-reversible mutation. The description adds that the target is the signed-in user's own stack (implying auth scope), but says nothing about what happens to historical data or whether the removal can be undone.

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

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

Three sentences, front-loaded with the trigger condition and the action, followed by the parameter note. No filler.

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

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

For a one-parameter destructive tool with no output schema, the description covers purpose, trigger, and the parameter's accepted forms. The remaining gap is behavioral consequence (reversibility, effect on stack score/history), which annotations only partially address.

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

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

Schema coverage is 100% and the schema only says 'SuppCo Product ID', while the description adds that the value may be a UUID or a slug and points to suppco_get_my_stack as the source. That is genuine meaning beyond the schema, though it omits any format example.

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

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

States a specific verb and resource ('Removes the product from the signed-in user's stack') and frames the motivating user situation. Clearly separable from suppco_add_to_stack and suppco_manage_stack without opening a schema.

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

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

Explicit when-to-use trigger: the user has stopped taking a product or wants it off their stack. It stops short of naming an alternative (e.g. suppco_manage_stack) or stating when not to use it, but the context is unambiguous.

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

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

Annotations already declare readOnlyHint=false, idempotentHint=false, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description usefully adds that only one *short* note is stored and that persistence is scoped to future SuppCo conversations, but it does not say what happens on repeated calls, whether notes can be replaced or deleted, or if any account permission is required.

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

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

Two short sentences with no waste, and the when-to-use trigger is front-loaded before the effect. Nothing could be removed without losing information.

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

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

For a one-parameter write tool with full annotation coverage and no output schema, the description supplies the trigger, the effect, and the persistence scope, which is close to everything an agent needs. Only the relationship to the profile-update sibling is left unaddressed.

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

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

With a single parameter at 100% schema description coverage, the schema already documents `memory` as 'The note to remember', establishing the 3 baseline. The description's 'one short note' adds a minor sizing/quantity hint for that parameter but no format or content guidance beyond it.

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

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

States a specific verb and resource — saving a short note about the user to their SuppCo account — so the effect is unambiguous. It does not distinguish itself from the sibling suppco_update_my_profile, which is also a write to the user's account, so an agent can't fully tell the two apart from the description alone.

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

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

Gives a clear trigger condition: use only when the user explicitly asks SuppCo to remember a preference or fact. That is stronger than implied usage, but it names no alternative (e.g., update_my_profile for structured profile data) and states no when-not to use it.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is covered. The description adds genuine value beyond that: the return is SuppCo's summaries of published studies with evidence grades, and it carries a medical disclaimer (no diagnosis, treatment, or recommendation). It does not discuss pagination or result volume.

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

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

Front-loaded with the primary usage trigger, then the return shape, then the disclaimer and sibling routing. Three dense sentences with little waste; the only minor redundancy is restating the two search modes already implied by the parameters.

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

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

There is no output schema, so the description usefully characterizes the return (study summaries with evidence grades) and frames the tool's limits. Both optional parameters, the zero-required-parameter case, and the sibling alternatives are all accounted for; only result breadth or pagination behavior is unaddressed.

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

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

Schema description coverage is 100% and both parameters are optional with their own examples and 'omit to search all' semantics already stated in the schema. The description adds no syntax, format, or matching behavior beyond what the schema provides, so the baseline 3 applies.

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

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

States a specific verb and resource ('search' for published research on a supplement's effects) and immediately clarifies scope with concrete examples (heart health, stress, focus). It also names two sibling tools it is not, so an agent can route without opening any schema.

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

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

Gives explicit when-to-use triggers (overall effects, effect on a specific health area, which supplements have the most research) and explicit alternatives with their own conditions: suppco_get_nutrient_info for dosing/nutrient basics and suppco_search_protocols for a full routine for a goal. Nothing is left to inference.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, covering the safety profile. The description adds only 'returns the matches', which is thin, and says nothing about result volume, ranking, or whether an empty match is possible. Adequate but not value-adding beyond 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.

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

Two sentences, zero waste, and the trigger condition is front-loaded before the disambiguation sentence. Every clause earns its place.

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

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

For a one-parameter, read-only search with no output schema, the description covers trigger, scope, and the sibling alternative. It could say slightly more about the shape or breadth of returned matches, but nothing essential for correct invocation is missing.

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

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

Schema coverage is 100% with a single 'query' parameter already documented in the schema. The description adds no syntax, format, or query-construction guidance beyond the example already present. Baseline 3 is appropriate when the schema carries the load.

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

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

States a specific verb and resource ('Searches SuppCo's protocols') plus the trigger domain (health goals like sleep, energy, weight loss). Explicitly distinguishes itself from suppco_get_my_protocols, so an agent can route without opening either schema.

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

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

Gives an explicit when-to-use condition ('when the user asks for a supplement protocol for a health goal') and names the alternative for the contrasting case (protocols the user already follows → suppco_get_my_protocols). Nothing is left to inference.

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

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

Annotations already declare destructiveHint=true, readOnlyHint=false and idempotentHint=false, so the safety profile is covered. The description adds real value beyond that by disclosing exactly what is destroyed (old_product_id removed from the stack) and that the removal and addition are described as a single operation. It does not cover failure behavior, e.g. what happens if old_product_id is not currently in the stack.

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

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

Two tight sentences, trigger first, mechanics second. Every clause carries information and nothing is padded.

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

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

For a two-parameter mutation with no output schema and annotations covering the safety profile, the description supplies purpose, trigger, effect, and identifier format. The only real omission is edge-case behavior on an invalid or absent old_product_id.

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

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

Schema coverage is 100% and the schema already labels both fields, so baseline is 3. The description earns an extra point by specifying the accepted identifier format ('SuppCo product UUIDs or slugs'), a detail the schema's generic 'SuppCo Product ID' wording does not provide.

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

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

States a specific verb+resource: 'replace a product in their stack with a different one', and spells out the mechanics (removes old_product_id, adds new_product_id). It implicitly separates itself from suppco_add_to_stack and suppco_remove_from_stack by being the atomic swap, but never names those siblings explicitly, so an agent must infer the distinction.

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

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

Gives a clear when-to-use trigger ('when the user wants to replace a product in their stack') and even a scenario ('after comparing alternatives') that points toward the compare tools. It stops short of stating when NOT to use it, e.g. that add_to_stack plus remove_from_stack would be the alternative for non-swap edits.

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

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

Annotations already declare idempotentHint, destructiveHint and openWorldHint, but the description adds genuine specifics beyond them: quantity is a new total rather than an increment (explaining why repeats are safe), and 0 is the destructive trigger that removes the item. It also notes the return value. Minor gap: no mention of auth requirements or what happens to a subscription item when quantity is set to 0.

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

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

Three tight sentences, front-loaded with the core action, then the non-obvious semantics, then the conditional flag. Every sentence carries information an agent needs; nothing is padding.

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

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

With an output schema present and full annotation coverage, the description supplies exactly the missing pieces: set-vs-increment semantics, the destructive zero case, and the disambiguation flag. An agent has everything required to invoke this correctly.

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

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

Schema description coverage is 100%, so the schema already documents all three parameters, including 'new total', '0 removes it', and the both-types condition for subscription. The description largely restates this at the prose level, adding the repeat-safety framing but no new syntax or format detail. Baseline 3 is appropriate.

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

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

States a specific verb and resource with an explicit scope constraint: 'Set the quantity of a product that is already in the signed-in user's cart.' The 'already in the cart' qualifier immediately separates it from suppco_add_to_cart and suppco_remove_from_cart without needing to open either schema.

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

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

Clearly establishes the trigger condition (item already in cart) and gives an explicit conditional rule for the optional subscription flag when a product exists as both a one-time purchase and a subscription, plus the 0-means-removal rule. It stops short of naming sibling tools (e.g. remove_from_cart or add_to_cart) as alternatives, so routing is implied rather than explicit.

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

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

Annotations already declare the mutation profile (readOnly=false, destructive=true, idempotent=true), and the description adds genuinely useful non-structured behavior: partial-merge semantics ('Only the fields you pass are changed') and overwrite semantics ('each one replaces the stored value'), plus the cross-tool side effect on product search ranking. It doesn't state permission/auth requirements or what happens to existing arrays like health_goals, 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.

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

Two tight sentences, with the usage trigger front-loaded before the behavioral details. The field enumeration in sentence one largely restates schema properties, so it isn't perfectly waste-free, but it doubles as a quick scan of scope.

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

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

For an 8-optional-parameter mutation tool with no output schema, the description covers the trigger, the merge/replace semantics, and the cross-tool consequence, which is most of what an agent needs. Minor gaps remain around array-field replacement behavior and confirmation of the resulting state.

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

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

Schema description coverage is 100% with enums and ranges documented inline, so the schema already carries parameter meaning. The description lists the field names but adds no format or syntax detail beyond what the schema provides; baseline 3 is appropriate.

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

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

The description states a specific verb (update/save) and resource (my profile) and enumerates the exact fields it accepts, so an agent knows precisely what this tool writes. It doesn't need to name a sibling because no other tool in the list updates profile data, though it also doesn't explicitly rule out overlap with suppco_save_memory.

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

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

The trigger is explicit: 'Use this when the user gives profile details they want saved.' It also explains downstream context (saved preferences change defaults for other SuppCo tools). It stops short of saying when NOT to use it or pointing at a specific alternative, but the usage condition is clear.

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

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

Annotations already declare destructiveHint=true and idempotentHint=true, and the word "Replaces" aligns with that by disclosing full-replacement semantics for the schedule rather than patching it. The description does not clarify that non-schedule fields (as_needed, with_food) are preserved when omitted, though the schema carries that detail.

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

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

Two sentences, trigger front-loaded and scope enumerated second, with no filler. The enumeration is a touch list-like but each item corresponds to a real capability an agent must expose.

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

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

For a 9-parameter mutation tool with full schema coverage, present destructive/idempotent annotations, and no output schema, the description supplies the trigger, the resource, and the replacement contract an agent needs. Remaining details live in structured fields where they belong.

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

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

Schema description coverage is 100%, so the schema already documents all 9 parameters in detail, including the change_daily_amount rejection rule and the units-vs-servings caveat. The description's enumeration of schedule aspects maps loosely onto parameters but adds no format, syntax, or constraint detail beyond the schema.

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

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

The description states a specific verb and resource ("Replaces that product's schedule") and scopes it to a product "already in their stack", which separates it cleanly from siblings like suppco_get_my_schedule and suppco_add_to_stack. It then enumerates the schedule dimensions it governs, so an agent knows exactly what this tool owns.

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

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

"Use this when the user wants to change when or how they take a product that is already in their stack" gives a clear trigger condition, and the 'already in stack' qualifier implicitly excludes new products. There is no explicit when-not or named alternative (e.g., add to stack for new products), so it stops short of full routing guidance.

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