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

package/src/toolSet/devaScore.js

@@ -7,36 +7,49 @@ import {z} from 'zod';
 function devaScore(_appContext) {
 
     let description = `
-deva-score — compute a numeric score based on two input values.
+## deva-score — compute a numeric score based on two input values
 
-USE when: calculate deva score, score these values, compute score for numbers
-DO NOT USE for: model scoring (use model-score), statistical calculations, data lookup
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- User wants to calculate the deva score: "Calculate deva score for 5 and 10"
+- User provides two numbers for scoring: "Score these values: 3 and 7"
+- User wants to compute a score in a series: "Calculate scores for [list of numbers]"
 
-PARAMETERS
-- a: number (required) — first input value
-- b: number (required) — second input value
+Do NOT use this tool for:
+- Scoring models (use model-score)
+- Statistical calculations beyond deva scoring
+- Looking up data or metadata
 
-FORMULA: (a + b) * 42
+Purpose
+Compute a numeric deva score by applying the formula (a + b) * 42 to two input numbers. For scoring more than two numbers, call this tool multiple times using the previous result as the first input (left-to-right fold).
 
-ROUTING RULES
-- "calculate deva score for 5 and 10" → { a: 5, b: 10 }
-- "score 1 and 2" → { a: 1, b: 2 }
-- "deva score a=3, b=7" → { a: 3, b: 7 }
-- Multiple numbers → chain calls left-to-right: call(first, second), then call(result, third)
+Parameters
+- a (number, required): First numeric input value
+- b (number, required): Second numeric input value
 
-EXAMPLES
+Response Contract
+Returns a numeric result: (a + b) * 42
+The result is always a number representing the computed deva score.
+
+Disambiguation & Clarification
+- If user provides more than two numbers without clear instructions: "Do you want to calculate the deva score by combining these numbers left-to-right?"
+- If user provides non-numeric input: "Please provide numeric values"
+
+Examples (→ mapped params)
 - "Calculate deva score for 5 and 10" → { a: 5, b: 10 } returns 630
 - "Score 1 and 2" → { a: 1, b: 2 } returns 126
-- "Deva score 20 and 30" → { a: 20, b: 30 } returns 2100
+- For multiple numbers, chain calls: devaScore(1,2)→126, then devaScore(126,3)→5418
+
+Negative Examples (should NOT call deva-score)
+- "Score this customer with the credit model" (use model-score instead)
+- "Calculate the mean of these values" (use run-sas-program or sas-query instead)
 
-NEGATIVE EXAMPLES (do not route here)
-- "Score this customer with credit model" (use model-score)
-- "Calculate the mean of these values" (use run-sas-program or sas-query)
-- "Statistical analysis of numbers" (use sas-query)
+Related Tools
+- None directly related (this is a specialized scoring tool)
 
-RESPONSE
-Returns { score: (a + b) * 42 }
-    `;
+Notes
+For sequences of numbers, use a left-to-right fold: call devaScore(first, second), then use that result as the first parameter for devaScore(result, third), and so on.
+`;
     let spec = {
         name: 'deva-score',
         aliases: ['devaScore','deva score','deva_score'],
@@ -47,15 +60,10 @@ Returns { score: (a + b) * 42 }
         },
         handler: async ({ a, b }) => {
             console.error( a, b);
-            let r = {score: (a + b) * 42};
-            console.error('deva score result', r);
-            return {
-                content: [{type: 'text', text: 'deva score result: ' + JSON.stringify(r)}],
-                structuredContent: r
-             };
-            }
+            return `MagicScore ${ (a + b) * 42 }`;
         }
         
+    }
     return spec;
 }
 export default devaScore;

package/src/toolSet/findJob.js

@@ -16,35 +16,61 @@ function findJob(_appContext) {
   "behavior": "Return only JSON matching response_schema when invoked by an LLM. If no matches, return { jobs: [] }"
 };
   let description = `
-find-job — locate a specific SAS Viya job.
+  ## find-job — locate a specific SAS Viya job
 
-USE when: find job, does job exist, is there a job named, lookup job, verify job exists
-DO NOT USE for: list jobs (use list-jobs), run job (use run-job), execute jobdef (use run-jobdef), find lib/table/model (use respective tools)
+  LLM Invocation Guidance
+  Use THIS tool when the user intent is to check if ONE job exists or retrieve its metadata:
+  - "find job cars_job_v4"
+  - "does job sales_summary exist"
+  - "is there a job named churnScorer"
+  - "lookup job forecast_monthly"
+  - "verify job ETL_Daily" 
 
-PARAMETERS
-- name: string (required) — job name to locate; if multiple supplied, use first
+  Do NOT use this tool when the user asks for:
+  - A list or browse of many jobs (use listJobs)
+  - Do not use this tool if the user want to find lib, find table, find model and similar requests
+  - Executing a job (use job)
+  - Running a job definition (use jobdef)
+  - Submitting arbitrary code (use program)
 
-ROUTING RULES
-- "find job <name>" → { name: "<name>" }
-- "does job <name> exist" → { name: "<name>" }
-- "is there a job named <name>" → { name: "<name>" }
-- "lookup/verify job <name>" → { name: "<name>" }
-- "find job" with no name → ask "Which job name would you like to find?"
-- "find all jobs / list jobs" → use list-jobs instead
-- "run job <name>" → use run-job instead
+  Purpose
+  Quickly determine whether a named job asset is present in the Viya environment and return its entry (or an empty result if not found).
 
-EXAMPLES
-- "find job cars_job_v4" → { name: "cars_job_v4" }
-- "does job ETL exist" → { name: "ETL" }
-- "is there a job named metricsRefresh" → { name: "metricsRefresh" }
+  Parameters
+  - name (string, required): Exact job name (case preserved). If multiple tokens/names supplied, take the first and ignore the rest; optionally ask for a single name.
 
-NEGATIVE EXAMPLES (do not route here)
-- "list jobs" (use list-jobs)
-- "run job cars_job_v4" (use run-job)
-- "execute jobdef cars_job_v4" (use run-jobdef)
+  Behavior & Matching
+  - Attempt exact match first (backend determines sensitivity).
+  - Returns { jobs: [...] } where array length is 0 (not found) or 1+ (if backend returns multiple with the same display name).
+  - No fuzzy guesses—never fabricate a job.
+  - If no name provided: ask "Which job name would you like to find?".
 
-ERRORS
-Returns { jobs: [] } if not found; { jobs: [name, ...] } if found. Never hallucinate job names.
+  Response Contract
+  - Always: { jobs: Array<string|object> }
+  - On error: propagate structured server error (do not wrap in prose when invoked programmatically).
+
+  Disambiguation Rules
+  - Input only "find job" → ask for missing name.
+  - Input contains verbs like "run" or "execute" → use run-job or run-jobdef instead.
+  - Input requesting many (e.g., "find all jobs") → use list-jobs.
+
+  Examples (→ mapped params)
+  - "find job cars_job_v4" → { name: "cars_job_v4" }
+  - "does job ETL exist" → { name: "ETL" }
+  - "is there a job named metricsRefresh" → { name: "metricsRefresh" }
+
+  Negative Examples (should NOT call find-job)
+  - "list jobs" (list-jobs)
+  - "run job cars_job_v4" (run-job)
+  - "execute jobdef cars_job_v4" (run-jobdef)
+
+  Clarifying Question Template
+  - Missing name: "Which job name would you like to find?"
+  - Multiple names: "Please provide just one job name (e.g. 'cars_job_v4')."
+
+  Notes
+  - For bulk existence checks loop over names and call find-job per name.
+  - Combine with run-job tool if user wants to execute after confirming existence.
   `;
 
   let spec = {

package/src/toolSet/findJobdef.js

@@ -15,36 +15,66 @@ function findJobdef(_appContext) {
   "behavior": "Return only JSON matching response_schema when invoked by an LLM. If no matches, return { jobs: [] }"
 };
   let description = `
-find-jobdef — locate a specific SAS Viya job definition.
+  ## find-jobdef — locate a specific SAS Viya job
 
-USE when: find jobdef, does jobdef exist, is there a jobdef named, lookup jobdef, verify jobdef exists
-DO NOT USE for: list jobdefs (use list-jobdefs), run jobdef (use run-jobdef), find job/lib/table/model (use respective tools)
+  LLM Invocation Guidance
+  Use THIS tool when the user intent is to check if ONE job exists or retrieve its metadata:
+  - "find jobdef cars_job_v4"
+  - "does jobdef sales_summary exist"
+  - "is there a jobdef named churnScorer"
+  - "lookup jobdef forecast_monthly"
+  - "verify jobdef ETL_Daily" 
 
-PARAMETERS
-- name: string (required) — jobdef name to locate; if multiple supplied, use first
+  Do NOT use this tool when the user asks for:
+  - find job  (use find-job)
+  - find table (use find-table
+  - find model (use find-model)
+  - find lib (use find-library)
+  - Executing a job (use job)
+  - Running a job definition (use jobdef)
+  - Submitting arbitrary code (use program)
 
-ROUTING RULES
-- "find jobdef <name>" → { name: "<name>" }
-- "does jobdef <name> exist" → { name: "<name>" }
-- "is there a jobdef named <name>" → { name: "<name>" }
-- "lookup/verify jobdef <name>" → { name: "<name>" }
-- "find jobdef" with no name → ask "Which jobdef name would you like to find?"
-- "find all jobdefs / list jobdefs" → use list-jobdefs instead
-- "run jobdef <name>" → use run-jobdef instead
+  Purpose
+  Quickly determine whether a named jobdef asset is present in the Viya environment and return its entry (or an empty result if not found).
 
-EXAMPLES
-- "find jobdef cars_job_v4" → { name: "cars_job_v4" }
-- "does jobdef ETL exist" → { name: "ETL" }
-- "is there a jobdef named metricsRefresh" → { name: "metricsRefresh" }
+  Parameters
+  - name (string, required): Exact jobdef name (case preserved). If multiple tokens/names supplied, take the first and ignore the rest; optionally ask for a single name.
 
-NEGATIVE EXAMPLES (do not route here)
-- "list jobdefs" (use list-jobdefs)
-- "run jobdef cars_job_v4" (use run-jobdef)
-- "find job ETL" (use find-job)
-- "find table cars" (use find-table)
+  Behavior & Matching
+  - Attempt exact match first (backend determines sensitivity).
+  - Returns { jobdefs: [...] } where array length is 0 (not found) or 1+ (if backend returns multiple with the same display name).
+  - No fuzzy guesses—never fabricate a job.
+  - If no name provided: ask "Which jobdef name would you like to find?".
 
-ERRORS
-Returns { jobdefs: [] } if not found; { jobdefs: [name, ...] } if found. Never hallucinate jobdef names.
+  Response Contract
+  - Always: { jobdefs: Array<string|object> }
+  - On error: propagate structured server error (do not wrap in prose when invoked programmatically).
+
+  Disambiguation Rules
+  - Input only "find job" → ask for missing name.
+  - Input contains verbs like "run" or "execute" → use run-job or run-jobdef instead.
+  - Input requesting many (e.g., "find all jobs") → use list-jobs.
+
+  Examples (→ mapped params)
+  - "find jobdef cars_job_v4" → { name: "cars_job_v4" }
+  - "does jobdef ETL exist" → { name: "ETL" }
+  - "is there a jobdef named metricsRefresh" → { name: "metricsRefresh" }
+
+  Negative Examples (should NOT call find-jobdef)
+  - find lib (use find-library)
+  - find table (use find-table)
+  - find model (use find-model)
+  - "list job" (list-jobdefs)
+  - "run job cars_job_v4" (run-job)
+  - "execute jobdef cars_job_v4" (run-jobdef)
+
+  Clarifying Question Template
+  - Missing name: "Which jobdef name would you like to find?"
+  - Multiple names: "Please provide just one jobdef name (e.g. 'cars_job_v4')."
+
+  Notes
+  - For bulk existence checks loop over names and call find-jobdef per name.
+  - Combine with run-jobdef tool if user wants to execute after confirming existence.
   `;
 
   let spec = {

package/src/toolSet/findLibrary.js

@@ -7,37 +7,69 @@ import _listLibrary from '../toolHelpers/_listLibrary.js';
 function findLibrary(_appContext) {
   
   let description = `
-find-library — locate a specific CAS or SAS library.
+  ## find-library — locate a specific CAS or SAS library
 
-USE when: find library, find lib, does library exist, is library available, lookup library
-DO NOT USE for: list libraries (use list-libraries), find table/job/jobdef/model (use respective tools), table structure (use table-info), create library (use run-sas-program)
+  LLM Invocation Guidance
+  Use THIS tool when the user asks any of the following (intent = existence / lookup of ONE library):
+  - "find library Public"
+  - "find lib Public"
+  - "does library SASHELP exist"
+  - "is PUBLIC library available in cas"
+  - "lookup library sasuser in sas"
+  - "show me library metadata for Models"
 
-PARAMETERS
-- name: string (required) — library/caslib name; if multiple supplied, use first
-- server: 'cas' | 'sas' (default: 'cas') — target environment
+  Aliases for lib are: library, caslib, libref
+  
+  Do NOT use this tool when the user wants:
+  - find model -> use find-model
+  - find table -> use find-table
+  - find job -> use find-job
+  - find jobdef -> use find-jobdef
+  - Columns or schema of a table (use table-info)
+  - Creating/assigning libraries (use run-sas-program or another admin tool)
+
+  Purpose
+  Quickly verify whether a single named library exists on CAS or SAS and return its entry (or empty if not found).
+
+  Parameters
+  - name (string, required) : Exact library (caslib) name to locate. If multiple names provided (comma/space separated), use the first and ignore the rest; optionally ask for one name.
+  - server (cas|sas, default 'cas') : Target environment. If omitted or ambiguous default to 'cas'.
+
+  Behavior & Matching
+  - Performs an exact name match (case-insensitive where backend supports it).
+  - Returns an object: { libraries: [...] } where the array contains zero or one items (backend may still return richer metadata).
+  - If no match: { libraries: [] } (do NOT fabricate suggestions).
+  - If user supplies no name: ask a clarifying question: "Which library name would you like to find?".
+  - If user clearly wants a list ("list", "show all", "enumerate") route to listLibrary instead.
+
+  Response Contract
+  - Always: { libraries: Array<string|object> }
+  - Never include prose when invoked programmatically; only the JSON structure.
+
+  Disambiguation Rules
+  - Input only "find library" → ask for the missing name.
+  - Input with both library name and words like "tables" → prefer listTables.
+  - Input like "find libraries" (plural) → prefer listLibrary unless user clarifies to a single name.
 
-ROUTING RULES
-- "find lib <name>" → { name: "<name>", server: "cas" }
-- "find lib <name> in cas" → { name: "<name>", server: "cas" }
-- "find library <name> in sas" → { name: "<name>", server: "sas" }
-- "does library <name> exist" → { name: "<name>", server: "cas" }
-- "find lib" with no name → ask "Which library name would you like to find?"
-- "list libraries / list libs" → use list-libraries instead
-- "tables in <lib>" → use list-tables instead
+  Examples (→ mapped params)
+  - "find lib Public" → { name: "Public", server: "cas" }
+  - "find library sasuser in sas" → { name: "sasuser", server: "sas" }
+  - "does library Formats exist" → { name: "Formats", server: "cas" }
+  - "is SystemData library in cas" → { name: "SystemData", server: "cas" }
 
-EXAMPLES
-- "find lib Public" → { name: "Public", server: "cas" }
-- "find library sasuser in sas" → { name: "sasuser", server: "sas" }
-- "does library Formats exist" → { name: "Formats", server: "cas" }
+  Negative Examples (should NOT call find-library)
+  - "list libs" (list-libraries)
+  -  Do not use this tool if the user want to find table, find job, find model, find job, find jobdef  and similar requests
+  - "show tables in Public" (list-tables)
+  - "describe table cars in sashelp" (table-info)
 
-NEGATIVE EXAMPLES (do not route here)
-- "list libs" (use list-libraries)
-- "show tables in Public" (use list-tables)
-- "find table cars in sashelp" (use find-table)
-- "find job cars_job" (use find-job)
+  Clarifying Question Template
+  - Missing name: "Which library name would you like to find?"
+  - Multiple names: "Please provide just one library name to look up (e.g. 'Public')."
 
-ERRORS
-Returns { libraries: [] } if not found; { libraries: [name, ...] } if found. Never hallucinate library names.
+  Notes
+  - For bulk validation of many names, call this tool repeatedly per name.
+  - For pagination or discovery, switch to list-libraries.
   `;
 
   let spec = {

package/src/toolSet/findModel.js

@@ -9,37 +9,59 @@ import _listModels from '../toolHelpers/_listModels.js';
 
 function findModel(_appContext) {
   let description = `
-find-model — locate a specific model deployed to MAS (Model Aggregation Service).
-
-USE when: find model, does model exist, is model deployed, lookup model, verify model exists
-DO NOT USE for: list models (use list-models), model info/variables (use model-info), score model (use model-score), find table/job/lib (use respective tools), scr models (use scr-info/scr-score)
-
-PARAMETERS
-- name: string (required) — model name to locate; if multiple supplied, use first
-
-ROUTING RULES
-- "find model <name>" → { name: "<name>" }
-- "does model <name> exist" → { name: "<name>" }
-- "is model <name> deployed" → { name: "<name>" }
-- "lookup/verify model <name>" → { name: "<name>" }
-- "find model" with no name → ask "Which model name would you like to find?"
-- "find all models / list models" → use list-models instead
-- "score model <name>" → use model-score instead
-- "describe model / model info" → use model-info instead
-
-EXAMPLES
-- "find model myModel" → { name: "myModel" }
-- "does model churn_score exist" → { name: "churn_score" }
-- "is model riskModel deployed" → { name: "riskModel" }
-- "lookup model claims_fraud_v1" → { name: "claims_fraud_v1" }
-
-NEGATIVE EXAMPLES (do not route here)
-- "list models" (use list-models)
-- "score model myModel" (use model-score)
-- "model info for churnRisk" (use model-info)
-
-ERRORS
-Returns { models: [] } if not found; { models: [name, ...] } if found. Never hallucinate model names.
+  ## find-model — locate a specific model deployed to MAS (Model Publish / Scoring service)
+
+  LLM Invocation Guidance (When to use)
+  Use THIS tool when the user wants to know whether ONE model exists or is deployed:
+  - "find model cancerRisk"
+  - "does model churn_tree exist"
+  - "is model sales_forecast deployed"
+  - "lookup model claimFraud"
+  - "verify model credit_score_v2 exists"
+
+  Do NOT use this tool for:
+  - Listing many / browsing models (use list-models)
+  - Retrieving detailed input/output variable metadata (use model-info)
+  - Scoring or running a model (use model-score)
+  - Searching model execution containers or SCR endpoints (use scr-info / scr-score if appropriate)
+  - Finding a table (use find-table)
+  - Finding a library (use find-library)
+  - Finding a job or jobdef (use find-job / find-jobdef)
+
+  Purpose
+  Quick existence / lookup check for a MAS‑published model. Returns a list with zero or more matches (typically 0 or 1 for an exact name).
+
+  Parameters
+  - name (string, required): Exact model name. If user supplies phrases like "model named X" extract X. If multiple names are given (comma or space separated), prefer the first and (optionally) ask for a single name.
+
+  Matching Rules
+  - Attempt exact match first. If backend supports partial search, a substring match MAY return multiple models; preserve order.
+  - Do not fabricate models. Empty array means not found.
+
+  Response Contract
+  - Always: { models: Array<object|string> }
+  - Never return prose when invoked programmatically; only the JSON structure.
+  - On error: surface backend error object directly (no rewriting) so the caller can display/log it.
+
+  Disambiguation & Clarification
+  - Missing name (e.g., "find model") → ask: "Which model name would you like to find?"
+  - Plural intent (e.g., "find models" / "list models") → use list-models instead.
+  - If user requests scoring ("score model X") → route to model-score not find-model.
+
+  Examples (→ mapped params)
+  - "find model myModel" → { name: "myModel" }
+  - "does model churn_score exist" → { name: "churn_score" }
+  - "is model riskModel deployed" → { name: "riskModel" }
+  - "lookup model claims_fraud_v1" → { name: "claims_fraud_v1" }
+
+  Negative Examples (should NOT call find-model)
+  - "list models" (list-models)
+  - "score model myModel" (model-score)
+  - "describe model myModel" (model-info)
+
+  Notes
+  - Chain usage: find-model → model-info → model-score.
+  - For batch existence checks iterate over a list and call find-model per entry.
   `;
 
   let spec = {

package/src/toolSet/findTable.js

@@ -9,39 +9,68 @@ import _listTables from '../toolHelpers/_listTables.js';
 
 function findTable(_appContext) {
   let description = `
-find-table — locate a specific table in a CAS or SAS library.
+## find-table — locate a specific table in a CAS or SAS library
 
-USE when: find table, does table exist, is table in library, verify table exists, locate table
-DO NOT USE for: list tables (use list-tables), table schema/columns (use table-info), read table data (use read-table), find lib/job/model (use respective tools)
+LLM Invocation Guidance (When to use)
+Use THIS tool when the user wants to find or verify a table in a specific library:
+- "find table iris in Public library in cas"
+- "find table cars in sashelp in sas server"
+- "does table customers exist in mylib?"
+- "is there a table named sales in the Samples library?"
+- "verify table orders exists in Public"
 
-PARAMETERS
-- lib: string (required) — library name (e.g., 'Public', 'sashelp')
-- name: string (required) — table name to locate
-- server: 'cas' | 'sas' (default: 'cas') — target environment
+Do NOT use this tool when the user wants:
+- find lib -> use find-library
+- find model -> use find-model
+- find job -> use find-job
+- find jobdef -> use find-jobdef
+- Columns or schema of a table (use table-info)
+- Reading data from a table (use read-table)
+- Listing all tables in a library (use list-tables)
 
-ROUTING RULES
-- "find table <name> in <lib>" → { lib: "<lib>", name: "<name>", server: "cas" }
-- "find table <name> in <lib> in sas" → { lib: "<lib>", name: "<name>", server: "sas" }
-- "does table <name> exist in <lib>" → { lib: "<lib>", name: "<name>", server: "cas" }
-- "find table" with missing lib → ask "Which library contains the table?"
-- "find table" with missing name → ask "Which table name would you like to find?"
-- "list tables in <lib>" → use list-tables instead
+Purpose
+Locate a table contained in a specified library (caslib or libref) on a CAS or SAS server. Returns matching table names or empty array if not found.
 
-EXAMPLES
-- "find table iris in Public" → { lib: "Public", name: "iris", server: "cas" }
-- "find table cars in sashelp in sas" → { lib: "sashelp", name: "cars", server: "sas" }
+Parameters
+- lib (string, required): The library to search in (e.g., 'Public', 'sashelp', or a caslib name)
+- name (string, required): Table name or substring to search for. Matching is case-insensitive.
+- server (string, default 'cas'): Either 'cas' or 'sas'. Defaults to 'cas' when omitted.
+
+Response Contract
+Returns a JSON object with:
+- tables: Array of matching table names (strings)
+- Empty array { tables: [] } when no matches found
+- Do not fabricate table names; only return actual matches
+
+Disambiguation & Clarification
+- Missing library: ask "Which library do you want to search in?"
+- Missing table name: ask "Which table name would you like to find?"
+- Server ambiguous: ask "Do you mean CAS or SAS?"
+- If user wants multiple tables: suggest "Use list-tables to see all tables in a library"
+
+Examples (→ mapped params)
+- "find table iris in Public library in cas" → { lib: "Public", name: "iris", server: "cas" }
+- "find table cars in sashelp in sas server" → { lib: "sashelp", name: "cars", server: "sas" }
 - "does customers exist in mylib" → { lib: "mylib", name: "customers", server: "cas" }
 - "verify table orders in Samples" → { lib: "Samples", name: "orders", server: "cas" }
 
-NEGATIVE EXAMPLES (do not route here)
-- "list tables in Public" (use list-tables)
-- "find library Public" (use find-library)
-- "what columns in cars?" (use table-info)
-- "read data from customers" (use read-table)
+Negative Examples (should NOT call find-table)
+- "list tables in Public" (use list-tables instead)
+- "find library Public" (use find-library instead)
+- "what columns in cars table?" (use table-info instead)
+- "read data from customers" (use read-table instead)
+
+Usage Tips
+- Use this tool to verify table existence before reading or querying
+- For discovery of multiple tables, use list-tables instead
+- After finding a table, use table-info for schema or read-table for data
 
-ERRORS
-Returns { tables: [] } if not found; { tables: [name, ...] } if found. Never hallucinate table names.
-  `;
+Related Tools
+- find-table → table-info → read-table (typical workflow)
+- list-tables — to discover all tables in a library
+- find-library — to verify library exists
+- table-info — to inspect table structure after finding it
+`;
   
   let spec = {
     name: 'find-table',

package/src/toolSet/getEnv.js

@@ -7,35 +7,53 @@ import {z} from 'zod';
 import _getEnv from '../toolHelpers/_getEnv.js';
 function getEnv(_appContext) {
     let description = `
-get-env — retrieve a variable value from the runtime environment.
+## get-env — retrieve a variable value from the runtime environment
 
-USE when: what is the value of, get me, show current, what's the, retrieve environment variable
-DO NOT USE for: read table data (use read-table), model info (use model-info), find/run job (use find-job/run-job), set context (use set-context)
+LLM Invocation Guidance (When to use)
+Use THIS tool when:
+- The user wants to access a specific environment variable or context value
+- "What is the value of [variable name]?"
+- "Get me the [variable] value"
+- "Show the current [variable]"
 
-PARAMETERS
-- name: string (required) — variable name to retrieve (case-sensitive)
+Do NOT use this tool for:
+- Retrieving table data (use read-table)
+- Getting model information (use model-info)
+- Looking up job status (use find-job or run-job)
+- Setting environment variables (use set-context to set CAS/SAS contexts)
 
-ROUTING RULES
-- "what is the value of <var>" → { name: "<var>" }
-- "get me <var>" → { name: "<var>" }
-- "show <var>" → { name: "<var>" }
-- "get" with no variable → ask "Which variable would you like to retrieve?"
-- "what context am I using" → use set-context instead (no params)
-- "set <var> to <value>" → use set-context or run-sas-program instead
+Purpose
+Retrieve the current value of a named variable from the runtime environment. This is useful for debugging, accessing context information, or verifying current configuration values.
 
-EXAMPLES
+Parameters
+- name (string, required): The name of the variable to retrieve. Variable names are case-sensitive.
+
+Response Contract
+Returns a JSON object containing:
+- The requested variable name as a key
+- The current value of that variable
+- If the variable does not exist, returns null or an error message
+
+Disambiguation & Clarification
+- If variable name is missing: ask "Which variable would you like to retrieve?"
+- If user says "context" without specifying which variable: clarify "Do you mean the CAS context, SAS context, or a specific variable?"
+- Multiple variable request: handle one at a time or ask for clarification
+
+Examples (→ mapped params)
 - "What's the value of myVar" → { name: "myVar" }
 - "Get me the configuration variable" → { name: "configuration" }
 - "Show the current server setting" → { name: "server" }
 
-NEGATIVE EXAMPLES (do not route here)
-- "Read rows from customers" (use read-table)
-- "Get model details for myModel" (use model-info)
-- "Set the CAS server to finance-prod" (use set-context)
+Negative Examples (should NOT call get-env)
+- "Read all rows from the customers table" (use read-table instead)
+- "Get model details for myModel" (use model-info instead)
+- "Set the CAS server to finance-prod" (use set-context instead)
 
-ERRORS
-Returns variable name with current value, or null if not found. Return structured error with message field.
-    `;
+Related Tools
+- setContext — to set environment context values (CAS and SAS servers)
+- readTable — to retrieve table data
+- modelInfo — to retrieve model metadata
+`;
   
     let spec = {
         name: 'get-env',