HerStack

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 meaningful behavioral context: it returns evidence rows with resolved PubMed and DOI identifiers, implying a lookup/verification behavior rather than a simple list. It doesn't mention pagination or result limits, but for a read-only lookup tool this is a minor 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?

Two sentences with no waste. The trigger condition is front-loaded, the resource is named, and the unique value (PubMed/DOI resolution) is included. Every sentence 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 read-only lookup tool with full schema coverage and safety annotations, the description is nearly complete. It explains the purpose, the trigger, and the unique output characteristic. It doesn't describe the exact return shape, but no output schema exists and the description's mention of resolved identifiers gives enough context for an agent to invoke it 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 both parameters. The description adds the context that topic and nutrient are used to find evidence rows, but it doesn't add syntax or format details beyond the schema. Baseline 3 is appropriate.

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

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

The description states a specific verb ('Call'), a clear resource ('HerStack's evidence rows'), and the purpose: retrieving studies behind a recommendation or claim. It also distinguishes itself from siblings by mentioning resolution to PubMed and DOI identifiers for verification, which is a unique capability.

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 description explicitly says when to call ('when the user or you wants the studies behind a recommendation or claim'), which is clear context. It doesn't explicitly name alternatives or exclusions, but the sibling list and the unique verification purpose make the usage context reasonably 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 readOnly, idempotent, non-destructive, and closed-world, so the safety profile is fully covered. The description adds the return payload contents, but says nothing about lookup failure (unknown SKU) or what happens when a product has no recommending topics, which would be the genuinely useful behavioral context here.

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 compact sentences, front-loaded with the invocation cue before the return contents. The field list in sentence two is dense but each item earns its place; 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?

There is no output schema, so the description correctly carries the return-value burden and enumerates the fields an agent will get back. It is nearly complete for a simple one-param read tool, lacking only edge-case behavior for unknown SKUs or missing recommendations.

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 'Product name or SKU, e.g. Chelated Magnesium'. The description's 'by name or SKU' restates that, adding no new semantics such as accepted SKU formats or fallback behavior on ambiguity.

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 and resource ('Call this for one specific product') and enumerates the returned fields (form, claim, tier, price, purchase link, recommending topics), which is far more specific than the title. It implicitly separates itself from recommend_supplements by scoping to a single product, but never names a sibling 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?

'Call this for one specific product' gives a clear triggering condition for a lookup-style call, but there is no when-not guidance, no statement of what to use for multi-product discovery, and no prerequisites (e.g. does the SKU have to exist in the HerStack catalogue).

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 disclose readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds value by explaining what the returned content covers (evidence table, FAQ, etc.), but does not add further behavioral constraints such as rate limits, required auth, or error handling. Given the annotation coverage, a 3 reflects useful but not rich additional behavioral context.

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?

The description is two sentences, with the 'when' condition first and a compact list of outputs second. The parenthetical example for perimenopause adds concrete detail without redundant words. There is no repetitive or vacuous content; every phrase carries 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 no output schema, the description does the necessary work of enumerating the return sections: plain-language framing, research findings, evidence table with authorised claims, product criteria, and FAQ. It also implies the usage by stating 'for perimenopause: what it is, its timeline, when to see a GP.' It lacks only lower-level details (e.g., exact response shape, error cases) that may be implied by the enum constraints.

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% – the lone 'topic' parameter is fully documented with an enum and concise helper text. The description does not add parameter-level detail beyond saying 'one topic', which is already structural in the schema. This meets the baseline 3 for full schema coverage.

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+resource: 'Call this when the user wants to understand a women's-health topic, not only buy something.' It enumerates the return composition (plain-language framing, research findings, evidence table, product criteria, FAQ), which clearly identifies the tool's primary function and differentiates it from purchase-related siblings by the 'not only buy something' clause.

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 explicit initial sentence 'Call this when the user wants to understand a women's-health topic' gives a clear trigger condition. The phrase 'not only buy something' provides a principal exclusion, guiding the agent away. However, it does not name the specific sibling alternatives (e.g., recommend_supplements), so the routing is implied rather than exhaustive, leaving some room for 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 only cover the safety profile (readOnly, idempotent, closed-world). The description adds real behavioral value by describing what comes back — named recommendations, formulation rationale, verbatim claim or a research-context note, price and purchase link — which is essential 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?

Front-loaded with the trigger, followed by return content, then input guidance. Three sentences, each earning its place, though the middle sentence enumerating return fields is dense enough to border on catalogue-like.

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-required-param lookup with no output schema, the description covers trigger, inputs and return shape adequately. It omits failure/empty-result behavior (e.g., when no authorized claim exists for a topic beyond the 'research-context note' hint), 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 coverage is 100%, so individual field meaning is already documented. The description goes beyond it by explaining the relationship between the two optional params: supply a topic, or supply a plain-word concern that routes to one — a routing semantic the enum alone does not convey.

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 + resource ('recommend supplements') with the exact output enumerated: named product picks, formulation rationale, verbatim health claim, price and purchase link. It is clearly distinguishable from get_product_details and get_evidence, which concern raw data rather than curated picks.

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 wants specific supplement product picks for a topic') and states the input condition (a topic or a plain-word concern that routes to one). It does not name a when-not case or explicitly hand off to search_guidance/get_topic_guidance in the description, though the schema hints at 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 carry the safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower; the description still adds real context by disclosing the return shape — answer units with page URLs, a best-matching topic, and named product recommendations each with its authorised claim. It omits any note on result ranking/fallback behaviour when nothing matches, 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?

Front-loaded with the actionable 'call this first' trigger and the example question, then the return payload. The single long sentence with a heavy parenthetical list is dense and slightly run-on, but every clause conveys selection-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 no output schema, the description must carry the return-value burden and does so thoroughly — enumerating content types, URLs, topic matching, and claim-bearing product cards. Combined with the when-to-use trigger, an agent has everything needed to invoke it correctly.

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

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

Schema description coverage is 100%, so both parameters are already documented in the schema. The description reinforces the free-text, user's-own-words nature of 'question' but adds no syntax or formatting detail, and never mentions maxResults — baseline 3 is appropriate when the schema does the work.

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 all of HerStack's evidence-led guidance for UK women in midlife') and then enumerates exactly what it returns (FAQ answers, research findings, evidence rows, product cards, meal plans). The 'Call this first' framing positions it as the entry point versus the narrower siblings like get_evidence and get_topic_guidance, so an agent can route 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 trigger condition ('when a user describes their situation or asks a question in their own words') reinforced by a concrete example query. It stops short of naming when NOT to use it or pointing to the sibling tools (get_product_details, recommend_supplements) for narrower intents, so it is clear but not fully routing-aware.

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