@sassoftware/sas-score-mcp-serverjs 0.4.0 → 0.4.1

package/src/toolSet/modelScore.js

@@ -10,33 +10,81 @@ const log = debug('tools');
 
 function modelScore(_appContext) {
   let description = `
-model-score — score data using a deployed model on MAS.
+## model-score — score data using a deployed model on MAS
 
-USE when: score with model, predict using model, batch scoring, model predictions
-DO NOT USE for: find model, model metadata, list models, run programs/jobs, query tables
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- User wants to score data with a model: "score this customer with model churnRisk"
+- User provides input values for prediction: "predict using model creditScore with age=45, income=60000"
+- User wants batch scoring: "score these 10 customers with fraud model"
+- User asks for model predictions: "what does the sales forecast model predict for Q4?"
+- User wants to get predictions: "use the risk model to score this applicant"
+- User provides scenario data for a model: "run model cancer1 with age=45, sex=M"
 
-PARAMETERS
-- model: string — model name (required, exact match)
-- scenario: string | object | array — input data (required). Accepts: "x=1, y=2", {x:1, y:2}, or array of objects
-- uflag: boolean (default: false) — prefix model fields with underscore when true
+Do NOT use this tool for:
+- Checking if a model exists (use find-model)
+- Getting model metadata/variables (use model-info)
+- Listing available models (use list-models)
+- Running SAS programs (use run-sas-program)
+- Running jobs (use run-job)
+- Querying tables (use sas-query or read-table)
 
-ROUTING RULES
-- "score with model X using a=1, b=2" → { model: "X", scenario: {a:1, b:2}, uflag: false }
-- "predict using model Y with age=45, income=60000" → { model: "Y", scenario: {age:45, income:60000}, uflag: false }
+Purpose
+Score user-supplied scenario data using a model published to MAS (Model Aggregation Service) on SAS Viya. Returns predictions, probabilities, scores, and other model outputs merged with the input data.
 
-EXAMPLES
-- "score with model churn using age=45, income=60000" → { model: "churn", scenario: {age:45, income:60000}, uflag: false }
-- "predict creditScore for credit=700, debt=20000" → { model: "creditScore", scenario: {credit:700, debt:20000}, uflag: false }
+Parameters
+- model (string, required): The name of the model as published to MAS. Must be exact match.
+- scenario (string | object | array, required): Data to score. Accepts:
+  - A comma-separated key=value string (e.g., "x=1, y=2")
+  - A plain object with field names and values (e.g., {x: 1, y: 2})
+  - An array of objects for batch scoring
+- uflag (boolean, default false): When true, returned model field names will be prefixed with an underscore.
 
-NEGATIVE EXAMPLES (do not route here)
-- "find model X" (use find-model)
-- "what inputs does model need" (use model-info)
-- "list models" (use list-models)
-- "run job X" (use run-job)
+Parsing & Behavior
+- If scenario is a string, the tool parses comma-separated key=value pairs into an object
+- If scenario is an array, supports batch scoring (processes multiple records)
+- Numeric values in strings remain as strings; validate and cast as needed before scoring
 
-ERRORS
-Returns predictions, probabilities, scores merged with input data. Returns error if model not found or scoring fails.
-  `;
+Response Contract
+Returns a JSON object containing:
+- Input fields merged with scoring results
+- Prediction/score field(s) from the model (field names depend on model)
+- Probability fields for classification models (e.g., P_class1, P_class2)
+- Model metadata: model name, version if available
+- _variables_: Variable metadata if uflag=true
+- Error object if scoring fails with error message
+
+Disambiguation & Clarification
+- Missing model name: ask "Which model would you like to use for scoring?"
+- Missing scenario data: ask "What input values should I use for scoring?"
+- If model unknown: suggest "Use find-model to verify the model exists or list-models to see available models"
+- If unsure of inputs: suggest "Use model-info to see the required input variables first"
+
+Examples (→ mapped params)
+- "score with model churn using age=45, income=60000" → { model: "churn", scenario: { age: "45", income: "60000" }, uflag: false }
+- "predict creditScore for applicant: credit=700, debt=20000" → { model: "creditScore", scenario: { credit: "700", debt: "20000" }, uflag: false }
+- "use fraud model to score transaction amount=500, merchant=online" → { model: "fraud", scenario: { amount: "500", merchant: "online" }, uflag: false }
+- "run model cancer1 with age=45, sex=M, tumor=stage2" → { model: "cancer1", scenario: { age: "45", sex: "M", tumor: "stage2" }, uflag: false }
+
+Negative Examples (should NOT call model-score)
+- "find model churnRisk" (use find-model instead)
+- "what inputs does model need?" (use model-info instead)
+- "list all models" (use list-models instead)
+- "run job scoring_job" (use run-job instead)
+- "read table scores from Public" (use read-table instead)
+
+Usage Tips
+- Use model-info first to understand required input variables and data types
+- Verify model exists with find-model before attempting to score
+- For batch scoring, provide an array of objects as the scenario parameter
+- Ensure MAS connectivity and credentials are available
+
+Related Tools
+- list-models → find-model → model-info → model-score (typical workflow)
+- find-model — to verify model exists before scoring
+- model-info — to understand required inputs and expected outputs
+- list-models — to discover available models
+`;
 
  
   let spec = {
@@ -71,12 +119,6 @@ Returns predictions, probabilities, scores merged with input data. Returns error
           }, {});
         }
       params.scenario= scenarioObj;
-      
-      // Drop model extension (e.g., .job, .model)
-      if (params.model && params.model.includes('.')) {
-        params.model = params.model.substring(0, params.model.lastIndexOf('.'));
-      }
-      
       log('modelScore params', params);
       // Check if the params.scenario is a string and parse it
       let r = await _masScoring(params)

package/src/toolSet/readTable.js

@@ -9,38 +9,75 @@ import _readTable from  '../toolHelpers/_readTable.js';
 function readTable(_appContext) {
    
      let describe = `
-read-table — retrieve rows from a table in a CAS or SAS library.
+## read-table — retrieve rows from a table in a CAS or SAS library
 
-USE when: read table, show rows, read from library, filtered data with WHERE
-DO NOT USE for: list tables, table structure (use table-info), SQL queries (use sas-query), SAS programs
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- User wants to read data from a table: "read table xyz.customers"
+- User wants sample rows: "show me 10 rows from lib.sales"
+- User wants filtered data: "read from mylib.orders where status = 'shipped'"
+- User wants from specific library: "read table cars in sashelp"
+- User wants from specific server: "read table from mylib.employees on sas"
 
-PARAMETERS
-- table: string — table name (required)
-- lib: string — caslib or libref (required)
-- server: string (default: 'cas') — 'cas' or 'sas'
-- start: number (default: 1) — 1-based row index
-- limit: number (default: 10) — max rows (1-1000)
-- where: string — SQL WHERE clause filter
-- format: boolean (default: true) — formatted or raw values
+Do NOT use this tool for:
+- Listing tables in a library (use list-tables)
+- Getting table structure/metadata (use table-info)
+- Running SQL queries (use sas-query)
+- Executing SAS programs (use run-sas-program)
+- Running statistical analysis (use appropriate analytics tools)
 
-ROUTING RULES
-- "read table cars in Samples" → { table: "cars", lib: "Samples", start: 1, limit: 10 }
-- "show 25 rows from customers" → { table: "customers", lib: "<lib>", limit: 25, start: 1 }
-- "read from mylib.orders where status='shipped'" → { table: "orders", lib: "mylib", where: "status='shipped'", start: 1, limit: 10 }
+Purpose
+Read one or more rows from a specified table in a CAS caslib or SAS libref. Supports pagination, filtering with WHERE clauses, and formatted/raw value display. Use this to inspect table data, sample rows, or retrieve filtered subsets.
+
+Parameters
+- table (string, required): Table name to read.
+- lib (string, required): The caslib or libref containing the table.
+- server (string, default 'cas'): Target server: 'cas' or 'sas'.
+- start (number, default 1): 1-based row index to start reading from.
+- limit (number, default 10): Maximum number of rows to return (1-1000 recommended).
+- where (string, optional): SQL-style WHERE clause to filter rows (e.g., "age > 30 AND status = 'active'").
+- format (boolean, default true): When true, return formatted/labeled values; when false return raw values.
+- row (number, optional): Read a single specific row (sets start to this value and limit to 1).
+
+Response Contract
+Returns a JSON object containing:
+- rows: Array of row objects with column names as keys
+- total (optional): Total count of rows in table (if available)
+- filtered_count (optional): Count of rows matching WHERE clause (if WHERE used)
+- columns (optional): Column metadata including names and types
+- Empty array if no rows match the criteria
+
+Pagination & Filtering
+- First page default: { start: 1, limit: 10 }
+- To get next page: increment start by limit (e.g., { start: 11, limit: 10 })
+- Use WHERE clause for server-side filtering: { where: "age > 30" }
+
+Disambiguation & Clarification
+- Missing library: ask "Which library contains the table you want to read?"
+- Missing table: ask "Which table would you like to read?"
+- Ambiguous lib.table format: parse and use as separate parameters
+- Multiple tables: clarify which one (readTable handles one table at a time)
 
-EXAMPLES
+Examples (→ mapped params)
 - "read table cars in Samples" → { table: "cars", lib: "Samples", start: 1, limit: 10 }
-- "show 25 rows from customers" → { table: "customers", lib: "mylib", limit: 25, start: 1 }
+- "show 25 rows from customers" → { table: "customers", lib: <current_lib>, limit: 25, start: 1 }
+- "read orders where status = 'shipped' limit 50" → { table: "orders", lib: <lib>, where: "status = 'shipped'", limit: 50, start: 1 }
+- "read row 15 from employees in mylib on sas" → { table: "employees", lib: "mylib", server: "sas", row: 15 }
+- "get next 10 rows" (after previous {start:1,limit:10}) → { table: <same>, lib: <same>, start: 11, limit: 10 }
 
-NEGATIVE EXAMPLES (do not route here)
-- "list tables in Samples" (use list-tables)
-- "what columns are in cars" (use table-info)
-- "execute SQL query" (use sas-query)
-- "run SAS code" (use run-sas-program)
+Negative Examples (should NOT call read-table)
+- "list tables in Samples" (use list-tables instead)
+- "what columns are in the cars table?" (use table-info instead)
+- "execute this SQL query" (use sas-query instead)
+- "run this SAS code" (use run-sas-program instead)
 
-ERRORS
-Returns rows array, total count, filtered_count, columns metadata. Empty array if no matches.
-  `;
+Related Tools
+- list-tables — to browse available tables in a library
+- table-info — to inspect table structure, columns, and metadata
+- find-table — to check if a table exists in a library
+- list-libraries — to browse available libraries
+- sas-query — to run complex SQL queries across tables
+`;
   
     let  specs = {
       name: 'read-table',

package/src/toolSet/runCasProgram.js

@@ -8,36 +8,56 @@ import _submitCode from '../toolHelpers/_submitCode.js';
 
 function runCasProgram(_appContext) {
   let description = `
-run-cas-program — execute a CAS program on SAS Viya server.
+## run-cas-program
 
-USE when: run cas program, execute cas, submit cas, cas action
-DO NOT USE for: macros (use run-macro), sas code (use run-sas-program), jobs (use run-job), jobdefs (use run-jobdef)
+Execute a cas program on a SAS Viya server
 
-PARAMETERS
-- src: string (required) — CAS program to execute verbatim
-- scenario: string or object (optional) — input parameters
-- folder: string — server folder path for .sas files
-- output: string — table name to return in response
-- limit: number (default: 100) — max rows to return
+Required Parameters
+- src(string, required): The cas program to execute. 
 
-ROUTING RULES
-- run cas program action echo → { src: action echo }
-- execute cas action simple.summary → { src: action simple.summary }
+Optional Parameters:
 
-EXAMPLES
-- run cas program action echo → { src: action echo }
-- cas program sample folder=/Public/models → { src: sample, folder: /Public/models }
+- scenario (string | object ,optional): Input values to program/ Accepts:
+  - a comma-separated key=value string (e.g. "x=1, y=2"),
+  - a JSON object with field names and values (recommended for typed inputs),
 
-NEGATIVE EXAMPLES (do not route here)
-- run sas macro (use run-macro)
-- submit sas code (use run-sas-program)
-- run job X (use run-job)
+LLM Invocation Guidance
+Use THIS tool when the user wants to run a Cas program on the server:
+- "run cas program 'action echo / code='aaaa'"
+- "cas program 'action echo / code='aaaa'"
+- 'submit cas "action echo / code='aaaa'"'
 
-NOTES
-Sends src verbatim without validation. For SAS macros use run-macro. For arbitrary SAS code use run-sas-program.
 
-RESPONSE
-Log output and CAS results. If output table specified, returned as markdown table.
+Do NOT use this tool when the user wants:
+- run macro -> use run-macro
+- submit sas -> use run-sas-program
+- run job -> use run-job
+- run sas  -> use run-sas-program
+- run jobdef -> use run-jobdef
+- run job -> use run-job
+- list jobs -> use list-jobs
+- list jobdefs -> use list-jobdefs
+- find job -> use find-job
+- find jobdef -> use find-jobdef
+- find model -> use find-model
+
+
+Behavior & usage notes
+- This tool sends the supplied \`src\` verbatim to the SAS execution helper. It does not modify or validate the SAS code.
+- For invoking pre-defined SAS macros, prefer the \`runMacro\` helper which converts simple parameter formats into \`%let\` statements and invokes the macro cleanly.
+- Be cautious when executing arbitrary code — validate or sanitize inputs in untrusted environments.
+
+Response
+- If output is specified and the specified table exists in the response, display the data as a markdown table. 
+Examples
+- run program "data a; x=1; run;"  - this is the simplest usage  -- {src= "data a; x=1; run;", folder=" ", output=" ", limit=100}
+- program "data work.a; x=1; run;" output=a limit=50  -- {src= "data work.a; x=1; run;", folder=" ", output="a", limit=50}
+
+- run program sample folder=/Public/models output=A limit=50 -- {src= "sample", folder="/Public/models", output="A", limit=50}
+- run program sample folder=/Public/models scenario="name='John', age=45" output=a limit=50 -- {src= "sample", folder="/Public/models", scenario: {name: "John", age: 45}, output="a", limit=50}
+- run program sample folder=/Public/models with scenario name=John,age=45 output=a limit=50  -- {src= "sample.sas", folder="/Public/models", scenario: {name: "John", age: 45}, output="a", limit=50}
+  - this should be the same as the previous example and is just a different syntax. The result should be
+    {program: "sample", folder: "/Public/models", scenario: {name: "John", age: 45}, output: "a", limit: 50}
 `;
 
   let spec = {

package/src/toolSet/runJob.js

@@ -9,31 +9,30 @@ import _jobSubmit from '../toolHelpers/_jobSubmit.js';
 function runJob(_appContext) {
  
   let description = `
-run-job — execute a deployed SAS Viya job.
+## run-job — execute a deployed SAS Viya job
 
-USE when: run job, execute job, run with parameters
-DO NOT USE for: arbitrary SAS code (use run-sas-program), macros (use run-macro), list/find jobs
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- You want to run a registered Job Execution asset by name
+- You have simple parameter inputs to pass to the job
 
-PARAMETERS
-- name: string — job name (required)
-- scenario: string | object — input parameters. Accepts: "x=1, y=2" or {x:1, y:2}
+Do NOT use this tool for:
+- Running arbitrary SAS code (use run-sas-program)
+- Invoking pre-defined SAS macros (use run-macro)
+- Listing or finding jobs (use list-jobs / find-job)
 
-ROUTING RULES
-- "run job xyz" → { name: "xyz" }
-- "run job xyz with param1=10, param2=val2" → { name: "xyz", scenario: {param1:10, param2:"val2"} }
+Parameters
+- name (string, required): The job name to execute
+- scenario (string | object, optional): Input values to the job. Accepts:
+  - a comma-separated key=value string (e.g. "x=1, y=2")
+  - a JSON object with field names and values (recommended)
 
-EXAMPLES
-- "run job xyz" → { name: "xyz" }
-- "run job monthly_etl with month=10, year=2025" → { name: "monthly_etl", scenario: {month:10, year:2025} }
+Response
+- Log output, listings, and tables depending on the job’s design. Table outputs will be displayed when present.
 
-NEGATIVE EXAMPLES (do not route here)
-- "run SAS code" (use run-sas-program)
-- "run macro X" (use run-macro)
-- "list jobs" (use list-jobs)
-- "find job X" (use find-job)
-
-ERRORS
-Returns log output, listings, tables from job. Error if job not found.
+Examples (→ mapped params)
+- "run job xyz param1=10,param2=val2" → { name: "xyz", scenario: { param1: 10, param2: "val2" } }
+- "run-job name=monthly_etl, scenario=month=10,year=2025" → { name: "monthly_etl", scenario: { month: 10, year: 2025 } }
 `;
 
   let spec = {

package/src/toolSet/runJobdef.js

@@ -6,36 +6,38 @@
 import { z } from 'zod';
 import _jobSubmit from '../toolHelpers/_jobSubmit.js';
 
+
 function runJobdef(_appContext) {
   // JSON object for LLM/tooling
  
   let description = `
-run-jobdef — execute a SAS Viya job definition.
-
-USE when: run jobdef, execute jobdef, run with parameters
-DO NOT USE for: arbitrary SAS code (use run-sas-program), macros (use run-macro), list/find jobdefs
+## run-jobdef — execute a SAS Viya job definition
 
-PARAMETERS
-- name: string — jobdef name (required)
-- scenario: string | object — input parameters. Accepts: "x=1, y=2" or {x:1, y:2}
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- You want to run a registered Job Definition by name
+- You can pass parameters to the job definition
 
-ROUTING RULES
-- "run jobdef xyz" → { name: "xyz" }
-- "run jobdef xyz with param1=10, param2=val2" → { name: "xyz", scenario: {param1:10, param2:"val2"} }
+Do NOT use this tool for:
+- Running arbitrary SAS code (use run-program tool)
+- Invoking SAS macros (use run-macro tool)
+- Listing or finding jobdefs (use list-jobdefs tool / find-jobdef tool)
 
-EXAMPLES
-- "run jobdef xyz" → { name: "xyz" }
-- "run jobdef monthly_report with month=10, year=2025" → { name: "monthly_report", scenario: {month:10, year:2025} }
+Parameters
+- name (string, required): The job definition name to execute
+- scenario (string | object, optional): Input values. Accepts:
+  - a comma-separated key=value string (e.g. "x=1, y=2")
+  - a JSON object with field names and values (recommended)
 
-NEGATIVE EXAMPLES (do not route here)
-- "run SAS code" (use run-sas-program)
-- "run macro X" (use run-macro)
-- "list jobdefs" (use list-jobdefs)
-- "find jobdef X" (use find-jobdef)
+Response
+- Log output, listings, and tables depending on the job definition's design. Table outputs will be displayed when present.
 
-ERRORS
-Returns log output, listings, tables from jobdef. Error if jobdef not found.
-  `;
+Examples (→ mapped params)
+- "jobdef xyz param1=10,param2=val2" → { name: "xyz", scenario: { param1: 10, param2: "val2" } }
+- "run jobdef name=monthly_report, scenario=month=10,year=2025" → { name: "monthly_report", scenario: { month: 10, year: 2025 } }
+- "run-jobdef xyz param1=10,param2=val2" → { name: "xyz", scenario: { param1: 10, param2: "val2" } }
+- "jobdef name=monthly_report, scenario=month=10,year=2025" → { name: "monthly_report", scenario: { month: 10, year: 2025 } 
+`;
  
   let spec = {
       name: 'run-jobdef',

package/src/toolSet/runMacro.js

@@ -9,32 +9,32 @@ import _submitCode from '../toolHelpers/_submitCode.js';
 
 function runMacro(_appContext) {
   let description = `
-run-macro — submit and execute a SAS macro on SAS Viya server.
+## run-macro
 
-USE when: run macro, execute macro with parameters
-DO NOT USE for: arbitrary SAS code (use run-sas-program), jobs, jobdefs
+Submit and execute a SAS macro on a SAS Viya server by generating and sending SAS code.
 
-PARAMETERS
-- macro: string — macro name without "%" (required)
-- scenario: string — parameters or setup code (optional). Accepts: "x=1, y=abc" or "%let x=1; %let y=abc;"
+Inputs
+- macro (string, required): The name of the macro to execute (provide the macro identifier without the leading "%").
+- scenario (string, optional): Parameters or SAS setup code to send before invoking the macro. Accepted formats:
+  - Comma-separated key=value pairs (e.g. "x=1, y=abc") — converted to SAS %let statements.
+  - Raw SAS macro code (e.g. "%let x=1; %let y=abc;") — passed through unchanged when it already contains SAS macro syntax.
 
-ROUTING RULES
-- "run macro abc" → { macro: "abc", scenario: "" }
-- "run macro abc with x=1, y=2" → { macro: "abc", scenario: "x=1, y=2" }
-- "run macro xyz with %let a=1; %let b=2;" → { macro: "xyz", scenario: "%let a=1; %let b=2;" }
+Behavior
+- If \`scenario\` contains SAS macro syntax (contains \`%let\` or other macro markers), it is sent unchanged.
+- Otherwise the tool converts comma-separated parameters into \`%let\` statements (e.g. "x=1,y=abc" → "%let x=1; %let y=abc;") and appends a macro invocation \`%<macro>;\`.
+- The resulting SAS code is submitted via the internal \`_submitCode\` helper and the submission result is returned.
 
-EXAMPLES
-- "run macro abc" → { macro: "abc", scenario: "" }
-- "run macro summarize with x=1, y=2" → { macro: "summarize", scenario: "x=1, y=2" }
+Output
+- Returns the response produced by \`_submitCode\`, typically including ods, log, list of tables created by the macro
 
-NEGATIVE EXAMPLES (do not route here)
-- "run SAS code" (use run-sas-program)
-- "run job X" (use run-job)
-- "run jobdef X" (use run-jobdef)
+Usage notes
+- Ensure the target SAS environment has the macro defined
+- This helper does not perform advanced input validation or type coercion — validate parameters before calling when needed.
 
-ERRORS
-Returns log, ods, tables created by macro. Auto-converts "x=1, y=2" to "%let x=1; %let y=2;" format.
-  `;
+Examples
+- run macro \`abc\` with scenario \`x=1, y=2\`
+- run macro \`summarize\` with raw SAS code \`%let x=1; %let y=2;\` (the helper will pass it through unchanged)
+`;
 
   let spec = {
     name: 'run-macro',

package/src/toolSet/runProgram.js

@@ -8,37 +8,84 @@ import _submitCode from '../toolHelpers/_submitCode.js';
 
 function runProgram(_appContext) {
   let description = `
-run-sas-program — execute SAS code or programs on SAS Viya server.
+## run-sas-program — execute SAS code or programs on SAS Viya server
 
-USE when: run program, execute SAS code, run .sas file
-DO NOT USE for: macros (use run-macro), jobs (use run-job), jobdefs (use run-jobdef), SQL queries (use sas-query), read data (use read-table)
+LLM Invocation Guidance (When to use)
+Use THIS tool when the user wants to run a SAS program on the server:
+- "run program 'data a; x=1; run;'"
+- "execute this SAS code: proc print data=sashelp.cars; run;"
+- "program 'data work.a; x=1; run;' output=a limit=50"
+- "run sas program sample folder=/Public/models output=A limit=50"
+- "run sas program with parameters name=John, age=45"
+- "execute SAS file myprogram.sas from /Public folder"
 
-PARAMETERS
-- src: string — SAS code or .sas filename (required)
-- folder: string (default: '') — server folder path for .sas files
-- scenario: string | object — parameter values. Accepts: "x=1, y=2" or {x:1, y:2}
-- output: string (default: '') — table name to return (case-sensitive)
-- limit: number (default: 100) — max rows from output
+Do NOT use this tool when the user wants:
+- run macro -> use run-macro
+- run job -> use run-job
+- run jobdef -> use run-jobdef
+- list jobs -> use list-jobs
+- list jobdefs -> use list-jobdefs
+- find job -> use find-job
+- find jobdef -> use find-jobdef
+- find model -> use find-model
+- Query tables with SQL -> use sas-query
+- Read table data -> use read-table
 
-ROUTING RULES
-- "run program 'data a; x=1; run;'" → { src: "data a; x=1; run;", folder: "", output: "", limit: 100 }
-- "run sas program sample folder=/Public/models" → { src: "sample", folder: "/Public/models", output: "", limit: 100 }
-- "run program with name=John, age=45" → { src: "<code>", scenario: {name:"John", age:45}, output: "", limit: 100 }
+Purpose
+Execute SAS code or programs on a SAS Viya server. Can run inline SAS code or execute .sas files stored on the server. Supports parameter passing via scenario values and can return output tables.
+
+Parameters
+- src (string, required): The SAS program to execute. Can be either:
+  - Inline SAS code as a string (e.g., "data a; x=1; run;")
+  - Name of a .sas file stored on the server (used with folder parameter)
+- folder (string, default ''): Server folder path where the .sas file is located (e.g., "/Public/models")
+- scenario (string | object, optional): Input parameter values. Accepts:
+  - Comma-separated key=value string (e.g., "x=1, y=2")
+  - JSON object with field names and values (recommended)
+- output (string, default ''): Table name to return in response (case-sensitive)
+- limit (number, default 100): Maximum number of rows to return from output table
+
+Response Contract
+Returns a JSON object containing:
+- log: Execution log from SAS
+- ods: ODS output if generated
+- tables: Array of table names created during execution
+- data: If output parameter specified, returns the table data (up to limit rows)
+- error: Error message if execution fails
+- Empty content if no results produced
 
-EXAMPLES
+Disambiguation & Clarification
+- Missing SAS code: ask "What SAS program or code would you like to execute?"
+- Inline code vs file unclear: ask "Do you want to run inline SAS code or execute a .sas file from the server?"
+- If output table not returned: clarify "The output table name is case-sensitive. Did you specify the exact name?"
+- If unclear about parameters: ask "What parameter values should I pass to the program?"
+
+Examples (→ mapped params)
 - "run program 'data a; x=1; run;'" → { src: "data a; x=1; run;", folder: "", output: "", limit: 100 }
-- "run sas file sample in /Public" → { src: "sample", folder: "/Public", output: "", limit: 100 }
+- "program 'data work.a; x=1; run;' output=a limit=50" → { src: "data work.a; x=1; run;", folder: "", output: "a", limit: 50 }
+- "run sas program sample folder=/Public/models output=A limit=50" → { src: "sample", folder: "/Public/models", output: "A", limit: 50 }
+- "run program mycode.sas in /Public with name=John, age=45" → { src: "mycode", folder: "/Public", scenario: { name: "John", age: 45 }, output: "", limit: 100 }
+
+Negative Examples (should NOT call run-sas-program)
+- "run macro summarize" (use run-macro instead)
+- "run job monthly_report" (use run-job instead)
+- "run jobdef etl_process" (use run-jobdef instead)
+- "how many customers by region in Public.customers" (use sas-query instead)
+- "read 10 rows from cars" (use read-table instead)
 
-NEGATIVE EXAMPLES (do not route here)
-- "run macro X" (use run-macro)
-- "run job X" (use run-job)
-- "run jobdef X" (use run-jobdef)
-- "SQL query" (use sas-query)
-- "read table" (use read-table)
+Behavior & Usage Notes
+- Sends the supplied src verbatim to the SAS execution helper
+- For .sas files, specify the file name (with or without .sas extension) and the folder path
+- For invoking pre-defined SAS macros, prefer run-macro which handles %let statements automatically
+- Scenario values are converted to macro variables when provided
+- Be cautious when executing arbitrary code in production environments
 
-ERRORS
-Returns log, ods, tables array, data (if output specified). Error if execution fails.
-  `;
+Related Tools
+- run-macro — for executing predefined SAS macros with parameters
+- run-job — for executing registered Job Execution assets
+- sas-query — for natural language SQL queries
+- read-table — for simple data retrieval
+`;
 
   let spec = {
     name: 'run-sas-program',