compare_supplementsLegacy comparison tool that may include catalog and affiliate data. Use compare_evidence for a commerce-free evidence comparison.
| Name | Required | Description | Default |
|---|---|---|---|
| supplement_a | Yes | ||
| supplement_b | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only, idempotent, non-destructive behavior. The description adds valuable context beyond annotations: 'Legacy' indicates potential deprecation or reliability concerns, and 'may include catalog and affiliate data' warns the agent that results may contain commercial/affiliate content, which is critical for interpreting outputs. This is meaningful supplementary behavioral transparency.
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 exceptionally concise, using two short sentences to convey purpose, legacy status, and a usage alternative. Every word adds value, and the key guidance is front-loaded. No redundancy or 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 tool with only two simple string parameters and no output schema, the description gives a basic understanding of purpose and guidance. However, it lacks information about what the comparison returns (format, structure) and does not compensate for missing parameter descriptions. The annotations and sibling context help, but the description alone feels minimally complete rather than fully self-sufficient.
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 0% schema coverage and no parameter descriptions in the input schema, the description needed to explain what 'supplement_a' and 'supplement_b' should contain (e.g., product names, IDs, or URLs). The description only mentions 'comparison tool' and does not clarify parameter formats or constraints, relying solely on the self-explanatory parameter names, which is insufficient for unambiguous invocation.
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 explicitly states this is a 'Legacy comparison tool' that may include catalog and affiliate data, clearly identifying the tool's function (comparing supplements/products). It also distinguishes itself from the sibling tool 'compare_evidence' by noting the commerce component, making its purpose unique and clear.
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 provides explicit usage guidance: it names the alternative 'compare_evidence' for commerce-free evidence comparison, indirectly telling the user when to choose this tool (when catalog/affiliate data is acceptable or desired) and when not to. This is a clear, actionable directive that aids tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.
The evidence tools (compare_evidence, get_citations, get_evidence_summary, query_evidence_map, search_evidence) and commerce tools (compare_supplements, get_price_history, get_product, recommend_for_goal, search_supplements) are clearly separated, but a few pairs like compare_evidence vs compare_supplements and search_evidence vs query_evidence_map could cause confusion despite different data sources being described.
All tool names follow a consistent verb_noun snake_case pattern (e.g., search_evidence, get_citations, compare_evidence), making it easy to predict functionality from the name.
The 10 tools are within a reasonable range, but the legacy commerce tools (compare_supplements, get_price_history, get_product, recommend_for_goal, search_supplements) add redundancy and could be trimmed without losing core functionality, making the set slightly over-sized.
The evidence surface fully covers search, summary, comparison, citation retrieval, and dataset querying, while the commerce tools provide complete product lookup, price history, and recommendation capabilities. No major gaps are apparent for the stated purpose.