Describe Column

The describe_column is a discovery tool that reports the catalog-wide values of a single product column. It is the second step after list_relevant_columns: given a relevant column, this tool provides detailed information about the values it holds across the catalog. This information can be used to build valid static filters for searches, populate facets, validate shopper input, or simply inform the agent about the catalog’s structure and content. Only columns determined to be ‘relevant’ are inspectable, ensuring that access is tiered by existing authorization.

type vs kind

values.kind describes the shape of the values returned: enumerated, tree, numeric, boolean, or unsupported. The response’s type, however, specifies the underlying attribute type from the schema (e.g., Enumerated, Name, Colors, Tree, Float). This mapping is often many-to-one; for instance, Enumerated, Name, and Colors all map to the enumerated kind, but a single type will never span multiple kinds. The type provides a more granular signal, guiding the agent’s interpretation of the values: for example, a Colors column’s entries are specific color tokens, while a Name column’s entries are proper names, even though both appear under the enumerated kind.

CAP-union Trade-off

For each attribute, the tool inspects all physical CAP-variant columns (confirmed, actual, and predicted) and produces a union of their values. This is a deliberate superset approach: a value present in any variant (e.g., only in a predicted variant) will be included, even if no product’s CAP-resolved value is that specific value. This design prioritizes avoiding false negatives by accepting potential false positives. Future tasks may introduce mechanisms for precision suppression.

Colors

When inspecting a Colors column, values stored as /-joined composites per product (e.g., “red/blue”) are automatically split into individual color tokens (e.g., “red”, “blue”). Each token is then rendered using its canonical Display form, such as "red" or "family > #rgb". This ensures that the tokens are presented in a format directly usable for filtering as dynamic_filters selections. Note that a static_filter equality match will target the exact stored color string and might not match multicolor products; this is a known limitation to be addressed in future filter-layer updates.

DescribeColumnRequest Schema

• column: The product column to inspect. This should be a column name previously returned by list_relevant_columns.

DescribeColumnResponse Schema

• column: The name of the inspected column, echoed from the request.
• type: The column’s attribute type (e.g., Enumerated, Name, Colors, Tree, Float). This provides finer-grained context than values.kind for interpreting the values.
• values: Type-dependent values discovered across the catalog for the specified column. This is a discriminated union based on kind:
  • kind: enumerated: Represents distinct values for Enumerated, Name, or Colors columns. For Colors columns, each entry is a single color token.
    • values: An array of strings, listing the distinct values.
  • kind: tree: Represents a category hierarchy for Tree columns.
    • root: An optional McpColumnTreeNode representing the root of the hierarchy. It is omitted if the tree is empty.
  • kind: numeric: Represents a numeric range for Float, Minimum, or Maximum columns.
    • min: An optional float, representing the minimum value found. Omitted if no finite minimum is available.
    • max: An optional float, representing the maximum value found. Omitted if no finite maximum is available.
  • kind: boolean: Represents boolean values for Boolean columns.
    • true_ratio: An optional float in the range [0, 1], indicating the share of decided values that are true. Omitted if no values are decided.
  • kind: unsupported: Indicates that no discrete values are introspected for this column type in the current version.
    • reason: A string providing the reason why the column type is unsupported.

McpColumnTreeNode Schema

Represents a node within a category hierarchy:

• path_element: A string representing one segment of a category path – this node’s specific element.
• children: An array of McpColumnTreeNode objects, representing the child nodes. It is empty for a leaf node.