[KM-625] Prompt-style Tool Descriptions

Add a DESCRIPTION constant to each of the 8 analytics compute tools,
written prompt-style (Summary / USE WHEN / DON'T USE WHEN -> other tool /
example questions) for the Planner to decide which tool to pick. English
body with Indonesian trigger-word equivalents in parentheses. comparison
also documents the group_a baseline / comparison-direction rule.

Final destination is ToolSpec.description once the wrapper layer is built.
No behavior change; 72 tests, ruff, and mypy strict all green.

src/tools/analytics/aggregation.py

@@ -34,6 +34,31 @@ def _clean(value: object) -> object:
     return value
 
 
+# Prompt-style description read by the Planner to decide WHEN to pick this tool.
+# Final destination is ToolSpec.description once the wrapper layer is built.
+DESCRIPTION = """\
+Summary: Group-by aggregation. Splits rows by one or more key columns and \
+computes aggregates per group (sum, mean, count, min, max, median, nunique). \
+Returns one row per group.
+
+USE WHEN the question groups a metric by a category — the tell-tale sign is \
+"per"/"each"/"by" a dimension. Trigger words: "per/each" (per/tiap), "by" \
+(berdasarkan), "breakdown", "total/average ... per ...".
+
+DON'T USE WHEN:
+  - it summarizes a column with no grouping -> analyze_descriptive
+  - it compares two specific groups (A vs B) -> analyze_comparison
+  - it splits a single total into shares -> analyze_contribution
+  - the grouping is over time periods -> analyze_trend
+
+Example questions:
+  - "total revenue per region"
+  - "average order value by customer segment"
+  - "how many distinct products were sold per store?"
+  - "count of orders for each status"
+"""
+
+
 def analyze_aggregate(
     df: pd.DataFrame,
     aggregations: dict[str, list[str]],

src/tools/analytics/comparison.py

@@ -33,6 +33,35 @@ class GroupNotFoundError(ValueError):
 
 
 
+# Prompt-style description read by the Planner to decide WHEN to pick this tool.
+# Final destination is ToolSpec.description once the wrapper layer is built.
+DESCRIPTION = """\
+Summary: Head-to-head comparison of one aggregated metric between TWO specific \
+groups of a dimension (group_a is the baseline). Reports each group's value, \
+the absolute and percent difference, and which side is higher.
+
+USE WHEN the question pits two named groups against each other. Trigger words: \
+"vs"/"versus", "compare" (bandingkan), "A or B", "difference between" \
+(selisih/beda antara), "higher/lower than".
+
+SETTING GROUPS: group_a is the BASELINE (the reference). The "comparison" field \
+reads as "group_b is {higher/lower/equal} than group_a", and diff = value_b - \
+value_a. Put the reference/older/expected side in group_a. E.g. "is this year \
+higher than last year" -> group_a=last year, group_b=this year.
+
+DON'T USE WHEN:
+  - it aggregates across many groups at once -> analyze_aggregate
+  - it splits a single total into shares -> analyze_contribution
+  - it tracks change over time -> analyze_trend
+
+Example questions:
+  - "compare revenue between Jakarta and Surabaya"
+  - "is the average order value higher for members or non-members?"
+  - "difference in churn between plan A and plan B"
+  - "male vs female average spend"
+"""
+
+
 def analyze_comparison(
     df: pd.DataFrame,
     dimension: str,

src/tools/analytics/decomposition.py

@@ -36,6 +36,31 @@ def _clean(value: object) -> object:
     return value
 
 
+# Prompt-style description read by the Planner to decide WHEN to pick this tool.
+# Final destination is ToolSpec.description once the wrapper layer is built.
+DESCRIPTION = """\
+Summary: Breaks a single total into per-category contributions (share of total) \
+in one snapshot, largest first, with cumulative share. Supports Pareto (80/20) \
+reasoning. Optional top_n folds the long tail into "Others".
+
+USE WHEN the question is about how a whole splits into parts, or which \
+categories dominate. Trigger words: "contribution" (kontribusi), "share" \
+(porsi/proporsi), "% of total" (persen dari total), "Pareto/80-20", "top \
+contributors", "which ... make up most".
+
+DON'T USE WHEN:
+  - it pits two specific groups against each other -> analyze_comparison
+  - it tracks change over time -> analyze_trend
+  - it just aggregates per group without share-of-total -> analyze_aggregate
+
+Example questions:
+  - "which products contribute most to total sales?"
+  - "what share of revenue comes from each region?"
+  - "top 5 customers by contribution to profit"
+  - "do 20% of items make up 80% of revenue?"
+"""
+
+
 def analyze_contribution(
     df: pd.DataFrame,
     dimension: str,

src/tools/analytics/descriptive.py

@@ -83,6 +83,33 @@ def _describe_one(series: pd.Series, metrics: tuple[str, ...]) -> dict[str, obje
     return out
 
 
+# Prompt-style description read by the Planner to decide WHEN to pick this tool.
+# Final destination is ToolSpec.description once the wrapper layer is built.
+DESCRIPTION = """\
+Summary: Descriptive statistics (EDA) for one or several columns in a single \
+call — center (mean, median, mode), spread (std, variance, min, max, Q1/Q3 \
+quartiles), distribution shape (skew), and completeness (null count & rate).
+
+USE WHEN the user asks for an overview, summary, or single-column statistics \
+of ONE or SEVERAL columns as a whole, with NO grouping and NO comparison \
+between groups. Trigger words: "overview/summary" (ringkasan), "average" \
+(rata-rata), "median", "spread/distribution" (sebaran), "how many nulls" \
+(berapa nilai kosong).
+
+DON'T USE WHEN:
+  - the question groups by something ("per"/"each"/"by") -> analyze_aggregate
+  - it compares two specific groups (A vs B) -> analyze_comparison
+  - it tracks a metric over time -> analyze_trend
+  - it checks data type, quality, duplicates, outliers, constants -> analyze_profile
+
+Example questions:
+  - "what's the average and median customer age?"
+  - "summarize the income column"
+  - "how is product price distributed?"
+  - "how many nulls are in the email column?"
+"""
+
+
 def analyze_descriptive(
     df: pd.DataFrame,
     column_ids: list[str],

src/tools/analytics/quality.py

@@ -82,6 +82,31 @@ def _profile_one(series: pd.Series) -> dict[str, object]:
     return out
 
 
+# Prompt-style description read by the Planner to decide WHEN to pick this tool.
+# Final destination is ToolSpec.description once the wrapper layer is built.
+DESCRIPTION = """\
+Summary: Per-column data-quality profile. For each column reports dtype, \
+inferred type, completeness (null count/rate), cardinality (distinct count/rate, \
+constant flag), and — for numeric columns — min/max/mean plus an IQR-based \
+outlier count; for non-numeric columns the most frequent value.
+
+USE WHEN the question is about the HEALTH of the data, not its statistics: \
+missing values, duplicates, data types, outliers, "is this clean enough to \
+analyze". Trigger words: "quality" (kualitas), "missing/nulls" (data kosong), \
+"data type" (tipe data), "duplicates/unique" (duplikat/unik), "outliers".
+
+DON'T USE WHEN:
+  - the user wants statistics like mean/median/std/skew -> analyze_descriptive
+  - it groups or compares -> analyze_aggregate / analyze_comparison
+
+Example questions:
+  - "is this dataset clean enough to analyze?"
+  - "which columns have a lot of missing values?"
+  - "what are the data types and unique counts per column?"
+  - "are there outliers in the amount column?"
+"""
+
+
 def analyze_profile(
     df: pd.DataFrame,
     column_ids: list[str] | None = None,

src/tools/analytics/relationship.py

@@ -44,6 +44,30 @@ def _clean(value: object) -> float | None:
     return None if math.isnan(f) else f
 
 
+# Prompt-style description read by the Planner to decide WHEN to pick this tool.
+# Final destination is ToolSpec.description once the wrapper layer is built.
+DESCRIPTION = """\
+Summary: Pairwise correlation across numeric columns (pearson, spearman, or \
+kendall). Returns a correlation matrix plus the strongest pairs ranked by \
+absolute strength.
+
+USE WHEN the question is about relationship or association between numeric \
+variables. Trigger words: "correlation" (korelasi), "related/relationship" \
+(hubungan/keterkaitan), "does X affect Y", "move together".
+
+DON'T USE WHEN:
+  - it implies causation — correlation is not causality; stay descriptive
+  - it compares two groups of one metric -> analyze_comparison
+  - it summarizes a single column -> analyze_descriptive
+
+Example questions:
+  - "is there a correlation between price and quantity sold?"
+  - "which variables are most related to revenue?"
+  - "do age and spending move together?"
+  - "show the correlation matrix for the numeric columns"
+"""
+
+
 def analyze_correlation(
     df: pd.DataFrame,
     column_ids: list[str] | None = None,

src/tools/analytics/segmentation.py

@@ -52,6 +52,31 @@ def _clean(value: object) -> object:
     return value
 
 
+# Prompt-style description read by the Planner to decide WHEN to pick this tool.
+# Final destination is ToolSpec.description once the wrapper layer is built.
+DESCRIPTION = """\
+Summary: Bins a NUMERIC column into segments and counts how rows distribute \
+across them (optionally aggregating another column per segment). Two modes: \
+explicit cut edges (e.g. age 0-18-35-60) or equal-frequency quantile buckets \
+(quartiles, deciles).
+
+USE WHEN the question asks to bucket/bracket a continuous number into ranges. \
+Trigger words: "segment" (segmen), "bucket/bracket" (kelompokkan ke rentang), \
+"age groups/tiers" (kelompok umur/tingkatan), "quartiles/deciles", "bins".
+
+DON'T USE WHEN:
+  - the category already exists (no binning needed) -> analyze_contribution
+  - it aggregates by an existing key -> analyze_aggregate
+  - it compares two named groups -> analyze_comparison
+
+Example questions:
+  - "split customers into age brackets 0-18, 18-35, 35-60"
+  - "bucket orders into value tiers"
+  - "divide users into spending quartiles"
+  - "how many customers fall in each income band?"
+"""
+
+
 def analyze_segment(
     df: pd.DataFrame,
     column: str,

src/tools/analytics/temporal.py

@@ -64,6 +64,30 @@ def _period_label(ts: pd.Timestamp, freq: str) -> str:
     return str(ts.strftime("%Y-%m-%d"))  # day / week
 
 
+# Prompt-style description read by the Planner to decide WHEN to pick this tool.
+# Final destination is ToolSpec.description once the wrapper layer is built.
+DESCRIPTION = """\
+Summary: Time-series trend of one metric over evenly-spaced periods (day, week, \
+month, quarter, year). Reports per-period points plus direction, absolute and \
+percent change, and a linear slope.
+
+USE WHEN the question is about movement over time — growth, decline, trend, \
+seasonality. Trigger words: "over time" (dari waktu ke waktu), "trend" (tren), \
+"monthly/yearly" (bulanan/tahunan), "growth" (pertumbuhan), "since/last N months".
+
+DON'T USE WHEN:
+  - it groups by a non-time category -> analyze_aggregate
+  - it compares two specific groups (A vs B) -> analyze_comparison
+  - it summarizes a column with no time axis -> analyze_descriptive
+
+Example questions:
+  - "how did monthly revenue change this year?"
+  - "show the sales trend over the last 12 months"
+  - "is the number of signups growing quarter over quarter?"
+  - "yearly profit from 2019 to 2024"
+"""
+
+
 def analyze_trend(
     df: pd.DataFrame,
     date_column: str,