Fix/skill top param pattern (Teradata#330)

* fix(skill): replace TOP :n with ROW_NUMBER() pattern in customisation skill

Teradata's parser rejects TOP followed by a bind-parameter placeholder (error 3707).
The example_tool.yml and the "Mixing styles" section of parameter-substitution.md
both used TOP :n, which is what caused the generated dba_running_sessions tool to
fail on first use. Replaced with a derived-table + ROW_NUMBER() + WHERE rn <= :n
pattern, which is safe for prepared statements. Added an explicit warning callout
in the reference doc covering TOP :n, TOP {n} (fragile), and SAMPLE :n.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* corrected SQL examples

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: 2 people

agentic/skills/teradata-mcp-customisation/examples/example_tool.yml

@@ -6,7 +6,8 @@
 #
 # Demonstrates:
 #   - identifier interpolation via {database_name}
-#   - value bind via :n
+#   - value bind via :n (in WHERE, not TOP — see parameter-substitution.md)
+#   - ROW_NUMBER() pattern to limit rows safely (TOP :n is a Teradata parse error)
 #   - parameter defaults (both args optional)
 #   - description fields that surface to the LLM
 # ============================================================================
@@ -28,14 +29,15 @@ dbc_top_tables_by_size:
       type_hint: int
       default: 10
   sql: |
-    SELECT TOP :n
+    SELECT
       TableName                                AS table_name,
       SUM(CurrentPerm)                         AS current_perm_bytes,
       SUM(PeakPerm)                            AS peak_perm_bytes,
       CAST(SUM(CurrentPerm) / 1024.0 / 1024.0
-           AS DECIMAL(18,2))                   AS current_perm_mb
+            AS DECIMAL(18,2))                   AS current_perm_mb
     FROM DBC.AllSpaceV
-    WHERE DataBaseName = '{database_name}'
+    WHERE DataBaseName = :database_name
       AND TableName   <> 'All'
     GROUP BY TableName
+    QUALIFY ROW_NUMBER() OVER (ORDER BY SUM(CurrentPerm) DESC) <= :n
     ORDER BY current_perm_bytes DESC

agentic/skills/teradata-mcp-customisation/reference/parameter-substitution.md

@@ -68,16 +68,33 @@ Allowed and common: identifiers via `{…}`, values via `:…`.
 top_n_by_size:
   type: tool
   sql: |
-    SELECT TOP :n DataBaseName, SUM(CurrentPerm) AS perm
-    FROM {database_name}.AllSpaceV
-    WHERE TableName = 'All'
-    GROUP BY DataBaseName
-    ORDER BY perm DESC
+    SELECT
+      TableName                                AS table_name,
+      SUM(CurrentPerm)                         AS current_perm_bytes,
+      SUM(PeakPerm)                            AS peak_perm_bytes,
+      CAST(SUM(CurrentPerm) / 1024.0 / 1024.0
+            AS DECIMAL(18,2))                   AS current_perm_mb
+    FROM DBC.AllSpaceV
+    WHERE DataBaseName = :database_name
+      AND TableName   <> 'All'
+    GROUP BY TableName
+    QUALIFY ROW_NUMBER() OVER (ORDER BY SUM(CurrentPerm) DESC) <= :n
+    ORDER BY current_perm_bytes DESC
   parameters:
     database_name: { type_hint: str, default: "DBC" }
     n:             { type_hint: int, default: 10 }
 ```
 
+> **Never use `TOP N` with a parameter — use `ROW_NUMBER()` instead.**  
+> `TOP :n` fails because Teradata's parser requires a literal integer immediately after
+> the `TOP` keyword, before bind-parameter substitution occurs (error 3707:
+> *"expected something like an integer … between the 'TOP' keyword and '?'"*).  
+> `TOP {n}` avoids the parse error (Python string-substitution produces a literal), but
+> it bypasses the prepared-statement layer entirely, which is fragile and injection-prone.  
+> The correct pattern is a derived-table with `ROW_NUMBER() OVER (ORDER BY …)` and
+> `WHERE rn <= :n` in the outer query — `:n` is then a normal value bind that works safely.
+> The same applies to `SAMPLE :n`.
+
 ## `type_hint` values
 
 Resolved against `{str, int, float, bool, list, dict, Any}`. Anything else (`"datetime"`, `"Decimal"`, …) silently falls back to `str`. If you need richer typing, validate inside your SQL (`CAST(:x AS DATE)`) instead.