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

package/src/toolSet/listTables.js

@@ -12,64 +12,35 @@ function listTables(_appContext) {
   const log = debug('tools');
 
     let description = `
-    ## list-tables — enumerate tables within a specific CAS or SAS library
-
-  LLM Invocation Guidance (When to use)
-  Use THIS tool when the user explicitly wants the tables inside ONE library:
-  - "list tables in Samples"
-  - "show tables in sashelp"
-  - "list cas tables in Public"
-  - "list 25 tables in Samples"
-  - "next tables" (after a prior listTables call)
-
-  Do NOT use this tool to list the following
-  - lib -> use list-libraries
-  - list models -> use list-models
-  - list jobs -> use list-jobs
-  - list jobdefs -> use list-jobdefs
-  - Finding whether a library exists (use find-library)
-  - Describing a single table's columns or metadata (use table-info)
-  - Reading table data rows (use read-table)
-  - Listing jobs/models (other specialized tools)
-
-  Purpose
-  Return the names (and possibly lightweight metadata) of tables contained in a specified library (CAS caslib or SAS libref).
-
-  Parameters
-  - lib (string, required): Library to inspect (e.g. "Samples", "sashelp").
-  - server (cas|sas, default 'cas'): Target environment; default when unspecified is CAS.
-  - limit (number, default 10): Page size.
-  - start (number, default 1): 1-based offset for pagination.
-  - where (string, optional): Filter expression (if supported by backend) or ignored safely.
-
-  Response Contract
-  - JSON: { tables: string[] [, start:number]? }
-  - tables array is empty when no matches.
-  - Include start = start + limit when length === limit (possible more pages).
-
-  Pagination Examples
-  - First page: { lib:'Samples', start:1, limit:10 }
-  - Next page:  { lib:'Samples', start:11, limit:10 }
-
-  Disambiguation & Clarification
-  - Missing library name → ask: "Which library do you want to list tables from?"
-  - Input only "list tables" → ask for the library unless prior context supplies one.
-  - If user mentions multiple libs ("tables in Public and Samples") → request a single library.
-
-  Negative Examples (should NOT call list-tables)
-  - "list libs" (list-libraries)
-  - "find lib Public" (find-library)
-  - "describe table cars" (table-info)
-  - "read table cars from sashelp" (read-table)
-
-  Usage Tips
-  - After listing, call table-info to inspect structure or read-table for sample data.
-  - Keep limit moderate; page for very large libraries.
-
-  Examples (→ mapped params)
-  - "list tables in samples" → { lib:"samples", start:1, limit:10 }
-  - "show 25 tables in sashelp" → { lib:"sashelp", limit:25, start:1 }
-  - "next tables" (after previous {start:1,limit:10}) → { start:11, limit:10, lib:<previousLib> }
+list-tables — enumerate tables within a library.
+
+USE when: list tables in <lib>, show tables in <lib>, next page
+DO NOT USE for: find table, list libraries, get table structure (use table-info), read data (use read-table)
+
+PARAMETERS
+- lib: string — library to inspect (required)
+- server: string (default: 'cas') — 'cas' or 'sas'
+- limit: number (default: 10) — page size
+- start: number (default: 1) — 1-based offset
+- where: string — optional filter expression
+
+ROUTING RULES
+- "list tables in Samples" → { lib: "Samples", start: 1, limit: 10 }
+- "list 25 tables in sashelp" → { lib: "sashelp", limit: 25, start: 1 }
+- "list cas tables in Public" → { lib: "Public", server: "cas", start: 1, limit: 10 }
+
+EXAMPLES
+- "list tables in Samples" → { lib: "Samples", start: 1, limit: 10 }
+- "show 25 tables in sashelp" → { lib: "sashelp", limit: 25, start: 1 }
+
+NEGATIVE EXAMPLES (do not route here)
+- "list libs" (use list-libraries)
+- "find lib Public" (use find-library)
+- "describe table cars" (use table-info)
+- "read table cars" (use read-table)
+
+ERRORS
+Returns empty array if no tables found.
   `;
     
   let spec = {

package/src/toolSet/makeTools.js

@@ -30,6 +30,7 @@ import findJobdef from './findJobdef.js';
 
 import sasQuery from './sasQuery.js';
 import setContext from './setContext.js';
+//import scoreSkill from './scoreSkill.js';
 
 function makeTools(_appContext) {
   // wrap all tools with 
@@ -64,6 +65,8 @@ function makeTools(_appContext) {
     findJobdef(_appContext),
     runJobdef(_appContext),
 
+    //scoreSkill(_appContext),
+
     devaScore(_appContext),
     setContext(_appContext)
     

package/src/toolSet/modelInfo.js

@@ -10,63 +10,32 @@ const log = debug('tools');
 
 function modelInfo(_appContext) {
   let description = `
-## model-info — retrieve detailed metadata for a deployed model
+model-info — retrieve detailed metadata for a deployed model.
 
-LLM Invocation Guidance (When to use)
-Use THIS tool when:
-- User wants input/output variable information: "What inputs does model X need?"
-- User wants to understand model variables: "Describe model myModel"
-- User wants data types and roles: "Show me the variables for myModel"
-- User wants to prepare data for scoring: "What are the required inputs for model sales_forecast?"
+USE when: what inputs does model need, describe model, show variables for model, model inputs/outputs
+DO NOT USE for: find model, list models, score model, table/job operations
 
-Do NOT use this tool for:
-- Checking if a model exists (use find-model)
-- Listing available models (use list-models)
-- Scoring a model (use model-score)
-- Looking up tables or jobs (use respective find/list tools)
+PARAMETERS
+- model: string — model name (required, exact match)
 
-Purpose
-Retrieve detailed metadata for a model deployed to MAS (Model Aggregation Service). This includes input variable names, data types, roles/usage, ranges, and output variable information. Use this before scoring to understand what data the model requires.
+ROUTING RULES
+- "what inputs does model X need?" → { model: "X" }
+- "describe model Y" → { model: "Y" }
+- "show variables for Z" → { model: "Z" }
 
-Parameters
-- model (string, required): The name of the model as published to MAS. Must be exact match.
-
-Response Contract
-Returns a JSON object containing model metadata, typically including:
-- name: The model name
-- inputs: Array of input variable objects with:
-  - name: Variable name
-  - type: Data type (numeric, character, etc.)
-  - role: Role in model (input, key, etc.)
-  - allowed_values or range: Optional constraints
-- outputs: Array of output/prediction objects with:
-  - name: Prediction/output variable name
-  - type: Data type
-  - possible_values: For classification models, the class labels
-- model_type: Type of model (regression, classification, etc.)
-- description: Optional model description
-
-Disambiguation & Clarification
-- If model name is missing: ask "Which model would you like to see information for?"
-- If user says "variables" without specifying model: ask "Which model would you like the variables for?"
-- Multiple model requests: handle one at a time
-
-Examples (→ mapped params)
+EXAMPLES
 - "What inputs does model churnRisk need?" → { model: "churnRisk" }
 - "Describe model creditScore" → { model: "creditScore" }
-- "Show the variables for myModel" → { model: "myModel" }
-- "What are the outputs of model sales_forecast?" → { model: "sales_forecast" }
+- "Show variables for myModel" → { model: "myModel" }
 
-Negative Examples (should NOT call model-info)
-- "List all available models" (use list-models instead)
-- "Find model cancer" (use find-model instead)
-- "Score this customer with model churnRisk" (use model-score instead)
+NEGATIVE EXAMPLES (do not route here)
+- "list models" (use list-models)
+- "find model X" (use find-model)
+- "score with model X" (use model-score)
 
-Related Tools
-- list-models → find-model → model-info → model-score (typical workflow)
-- find-model — to check if a specific model exists
-- model-score — to score data using the model
-`;
+ERRORS
+Returns model metadata: inputs (name, type, role), outputs (name, type, possible_values), model_type, description.
+  `;
 
   let spec = {
     name: 'model-info',

package/src/toolSet/modelScore.js

@@ -10,81 +10,33 @@ 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.
 
-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"
+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
 
-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)
+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
 
-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.
+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 }
 
-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.
+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 }
 
-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
+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)
 
-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
-`;
+ERRORS
+Returns predictions, probabilities, scores merged with input data. Returns error if model not found or scoring fails.
+  `;
 
  
   let spec = {
@@ -119,6 +71,12 @@ Related Tools
           }, {});
         }
       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,75 +9,38 @@ 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.
 
-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"
+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
 
-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)
+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
 
-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)
+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 }
 
-Examples (→ mapped params)
+EXAMPLES
 - "read table cars in Samples" → { table: "cars", lib: "Samples", start: 1, limit: 10 }
-- "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 }
+- "show 25 rows from customers" → { table: "customers", lib: "mylib", limit: 25, start: 1 }
 
-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)
+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)
 
-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
-`;
+ERRORS
+Returns rows array, total count, filtered_count, columns metadata. Empty array if no matches.
+  `;
   
     let  specs = {
       name: 'read-table',

package/src/toolSet/runCasProgram.js

@@ -8,56 +8,36 @@ import _submitCode from '../toolHelpers/_submitCode.js';
 
 function runCasProgram(_appContext) {
   let description = `
-## run-cas-program
+run-cas-program — execute a CAS program on SAS Viya server.
 
-Execute a cas program on a SAS Viya server
+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)
 
-Required Parameters
-- src(string, required): The cas program to execute. 
+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
 
-Optional Parameters:
+ROUTING RULES
+- run cas program action echo → { src: action echo }
+- execute cas action simple.summary → { src: action simple.summary }
 
-- 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),
+EXAMPLES
+- run cas program action echo → { src: action echo }
+- cas program sample folder=/Public/models → { src: sample, folder: /Public/models }
 
-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'"'
+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)
 
+NOTES
+Sends src verbatim without validation. For SAS macros use run-macro. For arbitrary SAS code use run-sas-program.
 
-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}
+RESPONSE
+Log output and CAS results. If output table specified, returned as markdown table.
 `;
 
   let spec = {

package/src/toolSet/runJob.js

@@ -9,30 +9,31 @@ 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.
 
-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
+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
 
-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)
+PARAMETERS
+- name: string — job name (required)
+- scenario: string | object — input parameters. Accepts: "x=1, y=2" or {x:1, y:2}
 
-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)
+ROUTING RULES
+- "run job xyz" → { name: "xyz" }
+- "run job xyz with param1=10, param2=val2" → { name: "xyz", scenario: {param1:10, param2:"val2"} }
 
-Response
-- Log output, listings, and tables depending on the job’s design. Table outputs will be displayed when present.
+EXAMPLES
+- "run job xyz" → { name: "xyz" }
+- "run job monthly_etl with month=10, year=2025" → { name: "monthly_etl", scenario: {month:10, year:2025} }
 
-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 } }
+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.
 `;
 
   let spec = {

package/src/toolSet/runJobdef.js

@@ -6,38 +6,36 @@
 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
+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
 
-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
+PARAMETERS
+- name: string — jobdef 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-program tool)
-- Invoking SAS macros (use run-macro tool)
-- Listing or finding jobdefs (use list-jobdefs tool / find-jobdef tool)
+ROUTING RULES
+- "run jobdef xyz" → { name: "xyz" }
+- "run jobdef xyz with param1=10, param2=val2" → { name: "xyz", scenario: {param1:10, param2:"val2"} }
 
-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)
+EXAMPLES
+- "run jobdef xyz" → { name: "xyz" }
+- "run jobdef monthly_report with month=10, year=2025" → { name: "monthly_report", scenario: {month:10, year:2025} }
 
-Response
-- Log output, listings, and tables depending on the job definition'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 jobdefs" (use list-jobdefs)
+- "find jobdef X" (use find-jobdef)
 
-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 } 
-`;
+ERRORS
+Returns log output, listings, tables from jobdef. Error if jobdef not found.
+  `;
  
   let spec = {
       name: 'run-jobdef',