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

Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the concrete response payload (cost_price, landing_cost_price, vendor_reference, vendor_name, vendor_packaging/MOQ, uom_ordering) and the underlying REST route, which is genuinely useful since there is no output schema. It stops short of documenting error behavior (e.g. unknown vendor_id) or currency/unit caveats on the cost fields.

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 compact fragments: the resource statement, the field list, and the endpoint. It is front-loaded with purpose and wastes little, though the raw field-list dump and trailing URL are terse rather than elegantly structured.

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 return-shape burden and does so by naming the returned fields, plus it exposes the REST path and the vendor_id format. For a simple two-parameter read this is nearly complete; only failure modes and pricing/unit semantics are absent.

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 documented there, including the lowercase-vendor-name convention. The description restates the same vendor_id rule ('the vendor name in lowercase') without adding format, casing edge cases, or what variant_id accepts beyond the schema. Baseline 3 is appropriate 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?

The description states the resource precisely ('One vendor's terms for a variant') and enumerates the fields returned, so an agent knows exactly what it gets. It implicitly separates itself from the list-style sibling by scoping to a single vendor, but it never names inventoryplanner_list_variant_vendors or inventoryplanner_get_variant as the alternatives, so sibling differentiation is left to inference.

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 rather than stated: the tool is clearly the singleton lookup once you already have a variant_id and vendor_id, and the schema notes vendor_id comes from inventoryplanner_list_variant_vendors. There is no explicit 'use this when X, use list_variant_vendors when Y' guidance or prerequisite/permission note in the description itself.

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