Machine Learning Doc Strings are too long

[dtehan-td]

We need to reduce machine learning doc strings

[dtehan-td]

There is a capability called skills within the MCP server that they are considering in the MCP specification, we will know how that plays out in June 2026. If we can move the how to use the tool to a skill then all the ML tools could be removed and run through a skill and the base_readQuery tool.

[dtehan-td]

Plan: reduce ML tool docstring size

Background

The ~89 tdml_* tools are dynamically registered in app.py:560-606 using teradataml's __init__.__doc__ as the MCP tool description. Those docstrings are very long (function summary + per-param block with Required/Optional, multi-line description, Default Value, Permitted Values, Types + EXAMPLES). Today's convert_tdml_docstring_to_mcp_docstring only trims at **generic_arguments and renames DataFrame → table name, so the verbose param sections survive verbatim.

The rest of the codebase (base/dba/sec/qlty/...) uses a consistent docstring shape:

<short description>

Arguments:
  <param> - <one-line description>

Returns:
  <one line>

The tdml_* tools should match that shape, and shrink in the process.

Approach: curated summary + auto-generated param section

Two sources fused at registration time:

(a) Curated one-line summary — hand-written, stored in constants.py. Replaces teradataml's multi-paragraph function summary.

(b) Compact param section — built from func_metadata.function_params at registration. Each param becomes one line: name + first-sentence description + Required/Optional + type. Drops Default Value, Permitted Values, EXAMPLES.

Final output per tool:

<curated one-line description>

Arguments:
  <param> - <first sentence of description>. <Required|Optional>. Types: <type>.
  ...
  output_table_name - Optional. Persist result to this table.
  database_name     - Optional. Database to use.

Returns:
  list of dicts, or table name when output_table_name is set.

File-by-file changes

1. src/teradata_mcp_server/tools/constants.py

   • Promote TD_ANALYTIC_FUNCS from list[str] to dict[str, str] mapping function name → one-line summary.
   • Seed each summary from the first sentence of teradataml's docstring, then hand-edit for clarity/brevity.

2. src/teradata_mcp_server/tools/utils/__init__.py

   • Add build_tdml_tool_docstring(summary: str, func_metadata, partition_order_cols: list[str]) -> str.
     • Reads func_metadata.function_params directly (no regex over teradataml docstring).
     • For each param: emit name - <first sentence>. <Required|Optional>. Types: <type>.
     • Append partition/order column lines (also one line each).
     • Append output_table_name, database_name, and Returns: block.
   • Shorten get_partition_col_order_col_doc_string to one line per column.
   • Remove convert_tdml_docstring_to_mcp_docstring (or keep as thin wrapper deprecated for one release if external callers exist — grep shows only app.py uses it).

3. src/teradata_mcp_server/app.py (lines 560-606)

   • Iterate TD_ANALYTIC_FUNCS.items() instead of the list.
   • Look up curated summary per function; skip with warning if missing.
   • Call build_tdml_tool_docstring(summary, func_metadata, additional_args_docs) instead of convert_tdml_docstring_to_mcp_docstring(init_doc, additional_args_docs).
   • Drop the init_doc = func_obj.__init__.__doc__ line — no longer needed.

Implementation steps

1. Convert TD_ANALYTIC_FUNCS to a dict, populate all 89 summaries (PR-reviewable wording change, no code wiring).
2. Add build_tdml_tool_docstring and shorten get_partition_col_order_col_doc_string.
3. Wire app.py to the new builder; remove the dead init_doc lookup.
4. Manually verify against a live DB: register tools, dump descriptions for KMeans, DecisionForest, XGBoost, ColumnSummary, Histogram. Confirm shape matches base tools and length is meaningfully smaller.
5. Update tests/cases if any reference old docstrings (none expected; tests are call-based).

Risks / tradeoffs

• 89 hand-written summaries — finite work but needs domain accuracy. Seeded from teradataml's first sentence.
• LLM loses Permitted Values lists and verbose param descriptions. For most tools, names + types + Required-flag are enough; failed calls return errors and retry. If specific tools turn out to need richer hints, add an optional details: field per entry later — easy follow-up.
• Drift risk — teradataml adds/renames a function and we silently don't register it. This is already true today (the list is hand-maintained), no regression.
• Param descriptions sourced from teradataml metadata still rely on teradataml quality. The first-sentence truncation may occasionally be awkward; we accept that for now.

Out of scope

The longer-term plan to replace ML tools with an MCP skill + base_readQuery (pending the MCP spec decision in June 2026) is not addressed here. This change is purely a size reduction for the existing tools and leaves that door open.

[dtehan-td]

@remi-td would you mind taking a look at the plan above and sharing your thoughts? Particularly interested in your take on (a) curating one-line summaries vs. parsing teradataml's first sentence, and (b) whether dropping Permitted Values from param descriptions is acceptable for the tools you've seen LLMs struggle with.