Use this when the user describes tables semantically (e.g. 'the table with customer orders', 'where we store payments'). Returns ranked hits with cosine scores plus the matched column and its LLM description so you see WHY each table surfaced. Use describe_table instead when the user names a specific table by qualified name. Common compositions: chain to describe_table for semantic-to-structural queries; chain to suggest_joins to discover then wire multi-table queries.

Use this when the user describes a business object (e.g. 'our customers', 'revenue data', 'product catalog'). Returns ranked entities — domain-named bindings to physical tables — so the agent stays in business terms. Use find_relevant_tables instead when no entities are curated. Common compositions: chain to describe_entity for one entity's full shape; chain to resolve_join to wire two entities together; chain to get_metric to compute a validated aggregation.

Use this when the user names a specific table by qualified name (e.g. 'show me public.orders'). Returns columns with types, nullability, primary-key flags, LLM descriptions, and outgoing foreign keys. Use find_relevant_tables instead when the user describes the table semantically. Common compositions: chain to describe_column to drill into one column's join graph; chain to suggest_joins to find paths from this table to others.

Use this when you need to drill into one column by its three-part qualified name (e.g. public.orders.user_id). Returns data type, nullability, default, LLM description, and BOTH join directions — outgoing FKs (this column joins out) and incoming FKs (which tables reference this column). Use describe_table instead when you want the whole table at once. Common composition: chain describe_table to describe_column to map a column's full role across schema.

Use this when you need real example SQL for an indexed table to learn how it's actually used. Each item carries the SQL text, observation count, source, and PII categories touched. Returns status: empty when the table has no recorded examples yet (query log mining ships next). Use describe_table instead when you want the table's structural shape rather than usage patterns. Common composition: chain find_relevant_tables to get_example_queries.

Use this when you already know two or more tables and need the join paths between them. Pass qualified names (schema.table) and get one shortest FK path per pair, with columns on each side ready for a SQL JOIN. Multi-hop paths via intermediates are returned; pairs with no path within max_hops (default 6) land in unreachable_pairs. Use find_relevant_tables instead when you don't yet know the table names. Common composition: chain find_relevant_tables to suggest_joins.

Use this when the user asks what semantic entities are defined (e.g. 'what entities do we have?', 'show me the entity list'). Returns every confirmed entity with its bound table, identity column, and provenance. Use describe_entity instead when you already know the entity name and want its full column shape. Common compositions: chain to describe_entity to drill in; chain to find_relevant_tables to discover physical tables that should become entities.

Use this when the user asks any ranking, top-N, most/highest/lowest, or aggregation question (e.g. 'who bought the most', 'top 5 by revenue', 'rank customers', 'find users with the highest X', 'what's the total / average / count') — returns every declared metric with its anchor entity, aggregation, and time-bucketing so you can pick the right metric before calling get_metric. Use get_metric instead when you already have the metric name. Chain to describe_entity for full anchor shape.

Use this when the user asks what canonical joins are defined (e.g. 'how are these entities connected?'). Returns each confirmed join with the entity pair it connects and provenance. Use resolve_join instead when you have a known pair and want the SQL skeleton (pass name= for 2+ joins on the pair). Use suggest_joins instead when only physical-table names are available.

Use this when the user names a specific entity (e.g. 'show me the customer entity', 'what's in the order entity'). Returns the entity's bound table, identity column, description, and full column list with PII sensitivity. Use list_entities instead when you don't yet know what entities exist. Common compositions: chain to describe_table to see the physical structure under the entity; chain to describe_column for one column's join graph.

Use this when you have two entity names and need the canonical SQL join between them. Returns a ready-to-paste JOIN clause with column mapping. Use suggest_joins instead when you only have physical table names. Don't use when you need to discover what entities exist — call list_entities first.

Use this when you have a metric name + want ranked/sliced rows (top-N, most/highest/lowest). Returns rows + parameterised SQL. Compiler chains multi-hop joins automatically (anchor order_item + group_by user.email + order_by total_items_sold desc → order_item → order → user). Pass order_by= for deterministic ranking; without it, limit is non-deterministic (envelope flags missing_order_by_with_limit). Use list_metrics instead when you don't know the metric name.