Retrieve linked products from orders or linked orders from products by traversing orderProducts links. Removes duplicate targets and supports direction when both ends share a type.
Follow orderProducts from a set of Order or Product. Duplicate target identities are removed. Direction is required when both ends have the same type.
| Name | Required | Description | Default |
|---|---|---|---|
| source | Yes | ||
| direction | No |
Changes observed during successful MCP inspections.
v0.5.1Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the behavioral disclosure burden. It does disclose useful behavior: duplicate target identities are removed and direction is required under certain conditions. However, it does not explain what 'forward' and 'reverse' mean, what the output looks like, or how errors are handled.
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 only two sentences and front-loads the core action. Each sentence adds relevant information, including duplicate removal and direction requirements. It is concise without being 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?
Given the absence of annotations and output schema, the description is insufficiently complete for an agent to confidently invoke the tool. It lacks the meaning of direction values, the shape of returned entities, and any examples or caveats. The tool involves a pivot relationship, which is more complex than a simple lookup, so more context is needed.
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 0%, so the description must compensate for the input schema. It partially does by indicating source types ('Order or Product') and the existence of a direction parameter, but it does not define the meaning of 'forward' or 'reverse', nor does it clarify the role of 'pks'. This leaves the agent inferring key parameter semantics.
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 uses a specific verb ('Follow orderProducts') and names the resource ('orderProducts') and the valid source types ('Order or Product'). It clearly states the core action. However, it does not explicitly distinguish itself from the sibling 'traverse_order_products', which appears to operate on the same relationship.
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 gives no explicit guidance about when to use this tool versus alternatives such as 'traverse_order_products' or 'get_product'. It only mentions a conditional rule about direction when both ends have the same type, which is a behavioral constraint rather than usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.